Changes - j0ke.net Open Build Service

@@ -1,6 +1,6 @@ -Metadata-Version: 1.0 +Metadata-Version: 1.1 Name: getmail -Version: 4.43.0 +Version: 4.46.0 Summary: a mail retrieval, sorting, and delivering system Home-page: http://pyropus.ca/software/getmail/ Author: Charles Cazabon

@@ -1,3 +1,25 @@ +Version 4.46.0 +6 April 2014 + -fix --idle checking Python version incorrectly, resulting in incorrect + warning about running with Python < 2.5. Thanks: "Voytek", Krzysztof + Warzecha. + -add missing support for SSL certificate checking in POP3 which broke + POP retrieval in v4.45.0. Requires Python 2.6 or newer. Thanks: "mancha". + +Version 4.45.0 +30 March 2014 + -perform hostname-vs-certificate matching of SSL certificate if validating + the certifcate. Thanks: "mancha". + -fix missing plaintext versions of documentation. + +Version 4.44.0 +22 March 2014 + -add extended SSL options for IMAP retrievers, allowing certificate + verification and other features. Thanks: Steven Murdoch. + -fix missing plaintext versions of documentation. Thanks: Osamu Aoki. + -fix "Header instance has no attribute 'strip'" error which cropped up + in some configurations. Thanks: Krzysztof Warzecha. + Version 4.43.0 25 August 2013 -add IMAP IDLE support. Thanks: Jon Gjengset.

@@ -74,6 +74,8 @@ <ul> <li><a href="configuration.html#conf-retriever-multidrop">What is a "multidrop" mailbox? How do I know if I have one?</a></li> <li><a href="configuration.html#retriever-parameters">Common retriever parameters</a></li> + <li><a href="configuration.html#retriever-ssl-client">SSL Client Parameters</a></li> + <li><a href="configuration.html#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a></li> <li><a href="configuration.html#retriever-simplepop3">SimplePOP3Retriever</a></li> <li><a href="configuration.html#retriever-brokenpop3">BrokenUIDLPOP3Retriever</a></li> <li><a href="configuration.html#retriever-simpleimap">SimpleIMAPRetriever</a></li> @@ -562,6 +564,10 @@ recognized, your Python installation does not have Gnome keyring integration support, or Gnome indicates that the keyring is not available. + If using the OSX keychain on 10.9 "Mavericks" (or later, presumably), + some additional steps may be necessary to make the password available to getmail + via the keychain. See <a href="http://article.gmane.org/gmane.mail.getmail.user/5120">this + posting to the getmail users' mailing list by Alan Schmitt</a> for details. </li> </ul> <p> @@ -630,6 +636,107 @@ </li> </ul> +<h4 id="retriever-ssl-client">SSL Client Parameters</h4> +<p> + All SSL-enabled retriever types also take the following options, to allow + specifying the use of a particular client key and client certificate + in establishing a connection to the server. +</p> +<ul> + <li> + keyfile + (<a href="#parameter-string">string</a>) + — use the specified PEM-formatted key file in the SSL negotiation. + </li> + <li> + certfile + (<a href="#parameter-string">string</a>) + — use the specified PEM-formatted certificate file in the SSL + negotiation. + </li> +</ul> + +<h4 id="retriever-ssl-extra">SSL Certificate Validation and Server Parameters</h4> +<p> + All SSL-enabled POP and IMAP retriever types also take the following options, + allowing you to require validation of the server's SSL certificate, or to check the + server's certificate fingerprint against a known good value, or to control + the specific SSL cipher used during the connection. +</p> +<p> + <strong>Note: using these features, including server certificate validation, + requires using Python 2.6 or Python 2.7 or higher with getmail.</strong> + If you use an earlier version of Python, these features will not work, and + no server certificate validation will be performed. + Also note that these features are not currently implemented for SPDS + retrievers; I would be interested in hearing from SPDS users who desire + these features. +</p> +<ul> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — advanced option to perform validation of the server's SSL + certificate. Specify the path to a PEM-formatted list of 1 or more + valid and trusted root certification authority (CA) certificates. + <strong>Note: this option is only available with Python 2.6 or higher.</strong> + <br /> + To find out which root CA is used to sign the chain of certificates for + a given server, you can run + <pre class="example"> +openssl s_client -showcerts -connect HOST:PORT < /dev/null 2>/dev/null \ + | grep '^[[:space:]]*i:' | tail -n 1 +</pre> + If the server's certificate cannot be validated based upon the supplied + trusted root certificates, getmail will abort the connection. + <br /> + Root certificates are not supplied with getmail; your OS probably installs a set + by default for use by the system, or you may wish to use a specific set of + trusted root certificates provided by your employer or a trusted third + party. Common locations for OS-supplied SSL root certification authority + certificates include: + <ul> + <li>Linux (Debian, Ubuntu, Arch, SuSE): <pre class="file">/etc/ssl/certs/</pre></li> + <li>Linux (RedHat, Fedora, CentOS): <pre class="file">/etc/pki/tls/certs/</pre></li> + <li>FreeBSD: <pre class="file">/usr/local/share/certs/</pre></li> + <li>OpenBSD: <pre class="file">/etc/ssl/</pre></li> + <li>OSX: <pre class="file">/System/Library/OpenSSL/certs/</pre></li> + <li>Windows: ask Microsoft</li> + </ul> + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — advanced option to control which SSL cipher algorithms will be + allowed to proceed. See the + <a href="http://www.openssl.org/docs/apps/ciphers.html">Open SSL documentation</a> + for details. + If the specified setting results in no possible ciphers available, + getmail will abort the connection. + <strong>Note: this option is only available with Python 2.7 or higher.</strong> + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — advanced option to control which SSL version getmail tries to + use to connect to the server; the default is "sslv23". Another + useful value is probably "sslv3". The available option values + are taken from the Python ssl module. + <strong>Note: this option is only available with Python 2.6 or higher.</strong> + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — advanced option to notice when the server's SSL certificate + changes. Supply a list of one or more SHA256 certificate fingerprints, + and getmail will confirm whether the server's certificate fingerprint is + in the list of allowed fingerprints; if it is not, getmail will abort + the connection. Getmail will log the fingerprint of the server's certificate + if you supply the <span class="file">--fingerprint</span> commandline option. + <strong>Note: this option is only available with Python 2.6 or higher.</strong> + </li> +</ul> + <h4 id="retriever-simplepop3">SimplePOP3Retriever</h4> <p> The SimplePOP3Retriever class takes the @@ -742,16 +849,28 @@ for definition. </li> <li> - keyfile + ca_certs (<a href="#parameter-string">string</a>) - — use the specified PEM-formatted key file in the SSL negotiation. - Note that no certificate or key validation is done. + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition </li> <li> - certfile + ssl_ciphers (<a href="#parameter-string">string</a>) - — use the specified PEM-formatted certificate file in the SSL - negotiation. Note that no certificate or key validation is done. + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition </li> </ul> @@ -773,16 +892,40 @@ keyfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> <li> certfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> </ul> <h4 id="retriever-simpleimapssl">SimpleIMAPSSLRetriever</h4> @@ -810,16 +953,40 @@ keyfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> <li> certfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> </ul> <h4 id="retriever-multidroppop3">MultidropPOP3Retriever</h4> @@ -896,16 +1063,40 @@ keyfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> <li> certfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> </ul> <h4 id="retriever-multidropsdps">MultidropSDPSRetriever</h4> @@ -1005,16 +1196,40 @@ keyfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> <li> certfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> </ul> <h3 id="retriever-examples">Retriever examples</h3> @@ -2732,7 +2947,7 @@ <p> If you are using a single getmailrc file with an IMAP server that understands the IDLE extension from <a href="http://www.rfc-editor.org/rfc/rfc2177.txt">RFC 2177</a>, - you can use the --rcfile=<span class="meta">MAILBOX</span> option to specify + you can use the --idle=<span class="meta">MAILBOX</span> option to specify that getmail should wait on the server to notify getmail of new mail in the specified mailbox after getmail is finished retrieving mail. </p>

@@ -0,0 +1,1629 @@ +getmail documentation + + This is the documentation for getmail version 4. Version 4 includes + numerous changes from version 3.x; if you are using getmail version 3, + please refer to the documentation included with that version of the + software. + + getmail is Copyright © 1998-2009 Charles Cazabon. + + getmail is licensed under the GNU General Public License version 2 + (only). If you wish to obtain a license to distribute getmail under + other terms, please contact me directly. + +Table of Contents + + * getmail documentation + * + + getmail documentation + + + o Features + o Differences from previous versions + o Requirements + o Obtaining getmail + o Installing getmail + o getmail mailing lists + * getmail configuration + * + + Configuring getmail + + + o Creating a getmail rc file + o + # Parameter types and formats + # + @ string + @ integer + @ boolean + @ tuple of quoted strings + @ tuple of integers + @ tuple of 2-tuples + # Creating the [retriever] section + # + @ What is a "multidrop" mailbox? How do I know if + I have one? + @ Common retriever parameters + @ SSL Client Parameters + @ SSL Certificate Validation and Server + Parameters + @ SimplePOP3Retriever + @ BrokenUIDLPOP3Retriever + @ SimpleIMAPRetriever + @ SimplePOP3SSLRetriever + @ BrokenUIDLPOP3SSLRetriever + @ SimpleIMAPSSLRetriever + @ MultidropPOP3Retriever + @ MultidropPOP3SSLRetriever + @ MultidropSDPSRetriever + @ MultidropIMAPRetriever + @ MultidropIMAPSSLRetriever + # Retriever examples + # Creating the [destination] section + # + @ Maildir + @ Mboxrd + @ MDA_external + @ MultiDestination + @ MultiSorter + @ MultiGuesser + @ MDA_qmaillocal + # Creating the [options] section + # + @ [options] example + # Creating the [filter-something] sections + # + @ Filter_classifier + @ Filter_external + @ Filter_TMDA + @ [filter-something] examples + # getmail rc file examples + + Running getmail + + + o Commandline options + o Using getmail as an MDA + o + # Using the getmail_maildir MDA + # + @ Example + # Using the getmail_mbox MDA + # + @ Example + o Using getmail_fetch to retrieve mail from scripts + * getmail troubleshooting + * + + Troubleshooting problems + + + o Error messages + o Warning messages + o Unexpected Behaviour + * getmail frequently-asked questions (FAQs) + * + + Frequently-Asked Questions (FAQs) + + + o About getmail + o Configuring getmail + o How do I … + o Using getmail with other software + o I think I found this bug in getmail … + +Configuring getmail + + Once getmail is installed, you need to configure it before you can + retrieve mail with it. Follow these steps: + 1. Create a data/configuration directory. The default is + $HOME/.getmail/. If you choose a different location, you will need + to specify it on the getmail command line. In general, other users + should not be able to read the contents of this directory, so you + should set the permissions on it appropriately. +mkdir -m 0700 $HOME/.getmail + + 2. Create a configuration file in the configuration/data directory. + The default name is getmailrc. If you choose a different filename, + you will need to specify it on the getmail command line. If you + want to retrieve mail from more than one mail account, you will + need to create a separate rc file for each account getmail should + retrieve mail from. + +Creating a getmail rc file + + The configuration file format is designed to be easy to understand + (both for getmail, and for the user). It is broken down into small + sections of related parameters by section headers which appear on lines + by themselves, enclosed in square brackets, like this: +[section name] + + Each section contains a series of parameters, declared as follows: +parameter_name = parameter_value + + A parameter value, if necessary, can span multiple lines. To indicate + that the second and subsequent lines form a continuation of the + previous line, they need to begin with leading whitespace, like this: +first_parameter = value + first parameter value continues here +second_parameter = value + + You can annotate your configuration files with comments by putting them + on lines which begin with a pound sign, like this: +first_parameter = value +# I chose this value because of etc. +second_parameter = value + + Each rc file requires at least two specific sections. The first is + retriever, which tells getmail about the mail account to retrieve + messages from. The second is destination, which tells getmail what to + do with the retrieved messages. There is also an optional section named + options , which gives getmail general configuration information (such + as whether to log its actions to a file), and other sections can be + used to tell getmail to filter retrieved messages through other + programs, or to deliver messages for particular users in a particular + way. + +Parameter types and formats + + Several different types of parameters are used in getmail rc files: + * string + * integer + * boolean + * tuple of quoted strings + * tuple of integers + * tuple of 2-tuples + + Each parameter type has a specific format that must be used to + represent it in the getmail rc file. They are explained below. Each + parameter documented later specifies its type explicitly. + +string + + Specify a string parameter value with no special syntax: +parameter = my value + +integer + + Specify an integer parameter value with no special syntax: +parameter = 4150 + +boolean + + A boolean parameter is true or false; you can specify its value with + the (case-insensitive) words "true" and "false". The values "yes", "on" + and 1 are accepted as equivalent to "true", while values "no", "off" + and 0 are accepted as equivalent to "false". Some examples: +parameter = True +parameter = false +parameter = NO +parameter = 1 + +tuple of quoted strings + + A tuple of quoted strings is essentially a list of strings, with each + string surrounded by matching double- or single-quote characters to + indicate where it begins and ends. The list must be surrounded by open- + and close-parenthesis characters. A tuple may have to be a specific + number of strings; for instance, a "2-tuple" must consist of two quoted + strings, while a "4-tuple" must have exactly four. In most cases, the + number of strings is not required to be a specific number, and it will + not be specified in this fashion. + + In general, a tuple of quoted strings parameter values should look like + this: +parameter = ('first string', 'second string', + "third string that contains a ' character") + + However, tuples of 0 or 1 strings require special treatment. The empty + tuple is specified with just the open- and close-parenthesis + characters: +parameter = () + + A tuple containing a single quoted string requires a comma to indicate + it is a tuple: +parameter = ("single string", ) + +tuple of integers + + This is very similar to a tuple of quoted strings, above, minus the + quotes. Some examples: +parameter = (1, 2, 3, 4, 5) +parameter = (37, ) +parameter = () + +tuple of 2-tuples + + This is a tuple of items, each of which is a 2-tuple of quoted strings. + You can think of this as a list of pairs of quoted strings. +# Three pairs +parameter = ( + ("first-a", "first-b"), + ("second-a", "second-b"), + ("third-a", "third-b"), + ) +# One pair +parameter = ( + ("lone-a", "lone-b"), + ) + +Creating the [retriever] section + + The retriever section of the rc file tells getmail what mail account to + retrieve mail from, and how to access that account. Begin with the + section header line as follows: +[retriever] + + Then, include a type string parameter to tell getmail what type of mail + retriever to use to retrieve mail from this account. The possible + values are: + * SimplePOP3Retriever — for single-user POP3 mail accounts. + * BrokenUIDLPOP3Retriever — for broken POP3 servers that do not + support the UIDL command, or which do not uniquely identify + messages; this provides basic support for single-user POP3 mail + accounts on such servers. + * SimpleIMAPRetriever — for single-user IMAP mail accounts. + * SimplePOP3SSLRetriever — same as SimplePOP3Retriever, but uses SSL + encryption. + * BrokenUIDLPOP3SSLRetriever — same as BrokenUIDLPOP3Retriever, but + uses SSL encryption. + * SimpleIMAPSSLRetriever — same as SimpleIMAPRetriever, but uses SSL + encryption. + * MultidropPOP3Retriever — for domain mailbox (multidrop) POP3 mail + accounts. + * MultidropPOP3SSLRetriever — same as MultidropPOP3Retriever, but + uses SSL encryption. + * MultidropSDPSRetriever — for domain mailbox SDPS mail accounts, as + provided by the UK ISP Demon. + * MultidropIMAPRetriever — for domain mailbox (multidrop) IMAP mail + accounts. + * MultidropIMAPSSLRetriever — same as MultidropIMAPRetriever, but + uses SSL encryption. + +What is a "multidrop" mailbox? How do I know if I have one? + + Some ISPs, mailhosts, and other service providers provide a mail + service they refer to as a "domain mailbox" or "multidrop mailbox". + This is where they register a domain for you, and mail addressed to any + local-part in that domain ends up in a single mailbox accessible via + POP3, with the message envelope (envelope sender address and envelope + recipient address) recorded properly in the message header, so that it + can be re-constructed after you retrieve the messages with POP3 or + IMAP. The primary benefit of this is that you can run your own MTA + (qmail, Postfix, sendmail, Exchange, etc.) for your domain without + having to have an SMTP daemon listening at a static IP address. + + Unfortunately, a lot of what is advertised and sold as multidrop + service really isn't. In many cases, the envelope recipient address of + the message is not properly recorded, so the envelope information is + lost and cannot be reconstructed. If the envelope isn't properly + preserved, it isn't a domain mailbox, and you therefore can't use a + multidrop retriever with that mailbox. + + To determine if you have a multidrop mailbox, check the following list: + if any of these items are not true, you do not have a multidrop + mailbox. + * the mailbox must receive one copy of the message for each envelope + recipient in the domain; if the message was addressed to three + local-parts in the domain, the mailbox must receive three separate + copies of the message. + * the envelope sender address must be recorded in a header field + named Return-Path at the top of the message. If the message + (incorrectly) already contained such a header field, it must be + deleted before the envelope sender address is recorded. + * the envelope recipient address must be recorded in a new header + field. These may be named various things, but are commonly + Delivered-To, X-Envelope-To, and similar values. In the case of + messages which had multiple recipients in the domain, this must be + a single address, reflecting the particular recipient of this copy + of the message. Note that this field (and the envelope recipient + address) are not related to informational header fields created by + the originating MUA, like To or cc. + + If you're not sure whether you have a multidrop mailbox, you probably + don't. You probably want to use SimplePOP3Retriever (for POP3 mail + accounts) or SimpleIMAPRetriever (for IMAP mail accounts) retrievers. + + Specify the mail account type with one of the above values, like this: +type = typename + + Then, include lines for any parameters and their values which are + required by the retriever. The parameters and their types are + documented below. + +Common retriever parameters + + All retriever types take several common required parameters: + * server (string) — the name or IP address of the server to retrieve + mail from + * username (string) — username to provide when logging in to the mail + server + + All retriever types also take several optional parameters: + * port (integer) — the TCP port number to connect to. If not + provided, the default is a port appropriate for the protocol (110 + for POP3, etc.) + * password (string) — password to use when logging in to the mail + server. If not using Kerberos authentication -- see below -- + getmail gets the password credential for the POP/IMAP server in one + of the following ways: + 1. from the password configuration item in the getmailrc file + 2. on Mac OS X only, from the OS X keychain + 3. on systems with Gnome keyring support, from the default Gnome + keyring + 4. if not found via any of the above methods, getmail will prompt + for the password when run + To store your POP/IMAP account password into the Gnome keyring, + ensure the password is not provided in the getmailrc file, and run + getmail with the special option --store-password-in-gnome-keyring; + getmail will run, prompt you for the password, store it in the + Gnome keyring, and exit without retrieving mail. If this option is + not recognized, your Python installation does not have Gnome + keyring integration support, or Gnome indicates that the keyring is + not available. If using the OSX keychain on 10.9 "Mavericks" (or + later, presumably), some additional steps may be necessary to make + the password available to getmail via the keychain. See this + posting to the getmail users' mailing list by Alan Schmitt for + details. + + All IMAP retriever types also take the following optional parameters: + * mailboxes (tuple of quoted strings) — a list of mailbox paths to + retrieve mail from, expressed as a Python tuple. If not specified, + the default is to retrieve mail from the mail folder named INBOX. + You might want to retrieve messages from several different mail + folders, using a configuration like this: +mailboxes = ("INBOX", "INBOX.spam", + "mailing-lists.model-railroading") + + Note that the format for hierarchical folder names is determined by + the IMAP server, not by getmail. Consult your server's + documentation or postmaster if you're unsure what form your server + uses. If your mailbox names contain non-ASCII characters, ensure + that your getmailrc file is stored with UTF-8 encoding so that + getmail can correctly determine the unicode character names that + need to be quoted in IMAP's modified UTF-7 encoding; if you do not + do this, the mailbox names will not match what the server expects + them to be, or will cause UnicodeErrors when attempting to load + your getmailrc file. As a special case, in getmail version 4.29.0 + and later, the unquoted base (non-tuple) value ALL (case-sensitive) + means to retrieve mail from all selectable IMAP mailboxes in the + account. To retrieve messages from all mailboxes, you would use: +mailboxes = ALL + + * use_peek (boolean) — whether to use PEEK to retrieve the message; + the default is True. IMAP servers typically mark a message as seen + if PEEK is not used to retrieve the message content. Versions of + getmail prior to 4.26.0 did not use PEEK to retrieve messages. + * move_on_delete (string) — if set, messages are moved to the named + mail folder before being deleted from their original location. Note + that if you configure getmail not to delete retrieved messages (the + default behaviour), they will not be moved at all. + * use_kerberos (boolean) — whether to use Kerberos authentication + with the IMAP server. If not set, normal password-based + authenticaion is used. Note that when you use Kerberos + authentication, it is up to you to ensure you have a valid Kerberos + ticket (perhaps by running a ticket-renewing agent such as kstart + or similar). This feature requires that a recent version of + pykerberos with GSS support is installed; check your OS + distribution or see http://honk.sigxcpu.org/projects/pykerberos/" + for details. + +SSL Client Parameters + + All SSL-enabled retriever types also take the following options, to + allow specifying the use of a particular client key and client + certificate in establishing a connection to the server. + * keyfile (string) — use the specified PEM-formatted key file in the + SSL negotiation. + * certfile (string) — use the specified PEM-formatted certificate + file in the SSL negotiation. + +SSL Certificate Validation and Server Parameters + + All SSL-enabled POP and IMAP retriever types also take the following + options, allowing you to require validation of the server's SSL + certificate, or to check the server's certificate fingerprint against a + known good value, or to control the specific SSL cipher used during the + connection. + + Note: using these features, including server certificate validation, + requires using Python 2.6 or Python 2.7 or higher with getmail. If you + use an earlier version of Python, these features will not work, and no + server certificate validation will be performed. Also note that these + features are not currently implemented for SPDS retrievers; I would be + interested in hearing from SPDS users who desire these features. + * ca_certs (string) — advanced option to perform validation of the + server's SSL certificate. Specify the path to a PEM-formatted list + of 1 or more valid and trusted root certification authority (CA) + certificates. Note: this option is only available with Python 2.6 + or higher. + To find out which root CA is used to sign the chain of certificates + for a given server, you can run +openssl s_client -showcerts -connect HOST:PORT < /dev/null 2>/dev/null \ + | grep '^[[:space:]]*i:' | tail -n 1 + + If the server's certificate cannot be validated based upon the + supplied trusted root certificates, getmail will abort the + connection. + Root certificates are not supplied with getmail; your OS probably + installs a set by default for use by the system, or you may wish to + use a specific set of trusted root certificates provided by your + employer or a trusted third party. Common locations for OS-supplied + SSL root certification authority certificates include: + + Linux (Debian, Ubuntu, Arch, SuSE): +/etc/ssl/certs/ + + Linux (RedHat, Fedora, CentOS): +/etc/pki/tls/certs/ + + FreeBSD: +/usr/local/share/certs/ + + OpenBSD: +/etc/ssl/ + + OSX: +/System/Library/OpenSSL/certs/ + + Windows: ask Microsoft + * ssl_ciphers (string) — advanced option to control which SSL cipher + algorithms will be allowed to proceed. See the Open SSL + documentation for details. If the specified setting results in no + possible ciphers available, getmail will abort the connection. + Note: this option is only available with Python 2.7 or higher. + * ssl_version (string) — advanced option to control which SSL version + getmail tries to use to connect to the server; the default is + "sslv23". Another useful value is probably "sslv3". The available + option values are taken from the Python ssl module. Note: this + option is only available with Python 2.6 or higher. + * ssl_fingerprints (tuple of quoted strings) — advanced option to + notice when the server's SSL certificate changes. Supply a list of + one or more SHA256 certificate fingerprints, and getmail will + confirm whether the server's certificate fingerprint is in the list + of allowed fingerprints; if it is not, getmail will abort the + connection. Getmail will log the fingerprint of the server's + certificate if you supply the --fingerprint commandline option. + Note: this option is only available with Python 2.6 or higher. + +SimplePOP3Retriever + + The SimplePOP3Retriever class takes the common retriever parameters + above, plus the following optional parameters: + * use_apop (boolean) — if set to True, getmail will use APOP-style + authentication to log in to the server instead of normal USER/PASS + authentication. This is not supported by many POP3 servers. Note + that APOP adds much less security than might be supposed; + weaknesses in its hashing algorithm mean that an attacker can + recover the first three characters of the password after snooping + on only a few hundred authentications between a client and server — + see http://www.securityfocus.com/archive/1/464477/30/0/threaded for + details. The default is False. + * timeout (integer) — how long (in seconds) to wait for socket + operations to complete before considering them failed. If not + specified, the default is 180 seconds. You may need to increase + this value in particularly poor networking conditions. + * delete_dup_msgids (boolean) — if set to True, and the POP3 server + identifies multiple messages as having the same "unique" + identifier, all but the first will be deleted without retrieving + them. + +BrokenUIDLPOP3Retriever + + This retriever class is intended only for use with broken POP3 servers + that either do not implement the UIDL command, or which do not properly + assign unique identifiers to messages (preventing getmail from + determining which messages it has seen before). It will identify every + message in the mailbox as a new message, and therefore if you use this + retriever class and opt not to delete messages after retrieval, it will + retrieve those messages again the next time getmail is run. Use this + retriever class only if your mailbox is hosted on such a broken POP3 + server, and the server does not provide another means of getmail + accessing it (i.e., IMAP). + + The BrokenUIDLPOP3Retriever class takes the common retriever parameters + above, plus the following optional parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * timeout (integer) — see SimplePOP3Retriever for definition. + +SimpleIMAPRetriever + + The SimpleIMAPRetriever class takes the common retriever parameters + above, plus the following optional parameters: + * timeout (integer) — see SimplePOP3Retriever for definition. + +SimplePOP3SSLRetriever + + The SimplePOP3SSLRetriever class takes the common retriever parameters + above, plus the following optional parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * delete_dup_msgids (boolean) — see SimplePOP3Retriever for + definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +BrokenUIDLPOP3SSLRetriever + + The BrokenUIDLPOP3SSLRetriever class takes the common retriever + parameters above, plus the following optional parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * keyfile (string) — see SSL Client Parameters for definition. + * certfile (string) — see SSL Client Parameters for definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +SimpleIMAPSSLRetriever + + The SimpleIMAPSSLRetriever class takes the common retriever parameters + above, plus the following optional parameters: + * mailboxes (tuple of quoted strings) — see common retriever + parameters for definition. + * move_on_delete (string) — see SimpleIMAPRetriever for definition. + * keyfile (string) — see SSL Client Parameters for definition. + * certfile (string) — see SSL Client Parameters for definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +MultidropPOP3Retriever + + The MultidropPOP3Retriever class takes the common retriever parameters + above, plus the following required parameter: + * envelope_recipient (string) — the name and position of the header + field which records the envelope recipient address. This is set to + a value of the form field_name : field_position . The first + (topmost) Delivered-To: header field would be specified as: +envelope_recipient = delivered-to:1 + + The MultidropPOP3Retriever also takes the following optional + parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * timeout (integer) — see SimplePOP3Retriever for definition. + +MultidropPOP3SSLRetriever + + The MultidropPOP3SSLRetriever class takes the common retriever + parameters above, plus the following required parameter: + * envelope_recipient (string) — see MultidropPOP3Retriever for + definition. + + The MultidropPOP3SSLRetriever class alo takes the following optional + parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * keyfile (string) — see SSL Client Parameters for definition. + * certfile (string) — see SSL Client Parameters for definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +MultidropSDPSRetriever + + The MultidropSDPSRetriever class takes the common retriever parameters + above, plus the following optional parameters: + * timeout (integer) — see SimplePOP3Retriever for definition. + +MultidropIMAPRetriever + + The MultidropIMAPRetriever class takes the common retriever parameters + above, plus the following required parameter: + * envelope_recipient (string) — see MultidropPOP3Retriever for + definition. + + The MultidropIMAPRetriever class also takes the following optional + parameters: + * timeout (integer) — see SimplePOP3Retriever for definition. + * mailboxes (tuple of quoted strings) — see common retriever + parameters for definition. + * move_on_delete (string) — see SimpleIMAPRetriever for definition. + +MultidropIMAPSSLRetriever + + The MultidropIMAPSSLRetriever class takes the common retriever + parameters above, plus the following required parameter: + * envelope_recipient (string) — see MultidropPOP3Retriever for + definition. + + The MultidropIMAPSSLRetriever class also takes following optional + parameters: + * mailboxes (tuple of quoted strings) — see common retriever + parameters for definition. + * move_on_delete (string) — see SimpleIMAPRetriever for definition. + * keyfile (string) — see SSL Client Parameters for definition. + * certfile (string) — see SSL Client Parameters for definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +Retriever examples + + A typical POP3 mail account (the basic kind of mailbox provided by most + internet service providers (ISPs)) would use a retriever configuration + like this: +[retriever] +type = SimplePOP3Retriever +server = popmail.isp.example.net +username = account_name +password = my_mail_password + + If your ISP provides POP3 access on a non-standard port number, you + would need to include the port parameter: +[retriever] +type = SimplePOP3Retriever +server = popmail.isp.example.net +port = 8110 +username = account_name +password = my_mail_password + + If your ISP provides POP3-over-SSL and you wanted to use that, your + retriever configuration might look like this: +[retriever] +type = SimplePOP3SSLRetriever +server = popmail.isp.example.net +username = account_name +password = my_mail_password + + If you have an IMAP mail account and want to retrieve messages from + several mail folders under that account, and you want to move messages + to a special folder when deleting them, you would use a retriever + configuration like this: +[retriever] +type = SimpleIMAPRetriever +server = imapmail.isp.example.net +username = account_name +password = my_mail_password +mailboxes = ("INBOX", "lists.unix", "lists.getmail") +move_on_delete = mail.deleted + + If you are retrieving your company's mail from a domain POP3 mailbox + for delivery to multiple local users, you might use a retriever + configuration like this: +[retriever] +type = MultidropPOP3Retriever +server = imapmail.isp.example.net +username = account_name +password = company_maildrop_password +envelope_recipient = delivered-to:1 + +Creating the [destination] section + + The destination section of the rc file tells getmail what to do with + retrieved messages. Begin with the section header line as follows: +[destination] + + Then, include a type string parameter to tell getmail what type of mail + destination this is. The possible values are: + * Maildir — deliver all messages to a local qmail-style maildir + * Mboxrd — deliver all messages to a local mboxrd-format mbox file + with fcntl-type locking. + * MDA_external — use an external message delivery agent (MDA) to + deliver messages. Typical MDAs include maildrop, procmail, and + others. + * MultiDestination — unconditionally deliver messages to multiple + destinations (maildirs, mbox files, external MDAs, or other + destinations). + * MultiSorter — sort messages according to the envelope recipient + (requires a domain mailbox retriever) and deliver to a variety of + maildirs, mbox files, external MDAs, or other destinations based on + regular expressions matching the recipient address of each message. + Messages not matching any of the regular expressions are delivered + to a default "postmaster" destination. + * MultiGuesser — sort messages according to getmail's best guess at + what the envelope recipient of the message might have been, and + deliver to a variety of maildirs, mbox files, external MDAs, or + other destinations based on regular expressions matching those + addresses. Messages not matching any of the regular expressions are + delivered to a default "postmaster" destination. + * MDA_qmaillocal — use qmail-local to deliver messages according to + instructions in a .qmail file. + +Maildir + + The Maildir destination delivers to a qmail-style maildir. The maildir + must already exist, and must contain all of the subdirectories required + by the maildir format. getmail will not create the maildir if it does + not exist. If you're not familiar with the maildir format, the + requirements in a nutshell are: it must be a directory containing three + writable subdirectories cur, new, and tmp, and they must all reside on + the same filesystem. + + The Maildir destination takes one required parameter: + * path (string) — the path to the maildir, ending in slash (/). This + value will be expanded for leading ~ or ~USER and environment + variables in the form $VARNAME or ${VARNAME}. You might want to + deliver messages to a maildir named Maildir in your home directory; + you could do this with a configuration like this: +[destination] +type = Maildir +path = ~/Maildir/ + + The Maildir destination also takes two optional parameters: + * user (string) — on Unix-like systems, if supplied, getmail will + change the effective UID to that of the named user before + delivering messages to the maildir. Note that this typically + requires root privileges. getmail will not deliver to maildirs as + root, so this "optional" parameter is required in that situation. + * filemode (string) — if supplied, getmail will cause the delivered + message files in the maildir to have at most these permissions + (given in standard Unix octal notation). Note that the current + umask is masked out of the given value at file creation time. The + default value, which should be appropriate for most users, is + "0600". + +Mboxrd + + The Mboxrd destination delivers to an mboxrd-format mbox file with + either fcntl-type (lockf) or flock-type file locking. The file must + already exist and appear to be a valid mboxrd file before getmail will + try to deliver to it — getmail will not create the file if it does not + exist. If you want to create a new mboxrd file for getmail to use, + simply create a completely empty (0-byte) file. + + You must ensure that all other programs accessing any the mbox file + expect mboxrd-format mbox files and the same type of file locking that + you configure getmail to use; failure to do so can cause mbox + corruption. If you do not know what type of file locking your system + expects, ask your system administrator. If you are the system + administrator and don't know what type of file locking your system + expects, do not use Mboxrd files; use Maildirs instead. Note that + delivering to mbox files over NFS can be unreliable and should be + avoided; this is the case with any MDA. + + The Mboxrd destination takes one required parameter: + * path (string) — the path to the mbox file. This value will be + expanded for leading ~ or ~USER and environment variables in the + form $VARNAME or ${VARNAME}. You might want to deliver messages to + an mbox file named inbox in your home directory; you could do this + with a configuration like this: +[destination] +type = Mboxrd +path = ~/inbox + + The Mboxrd destination also takes two optional parameters: + * user (string) — on Unix-like systems, if supplied, getmail will + change the effective UID to that of the named user before + delivering messages to the mboxrd file. Note that this typically + requires root privileges. getmail will not deliver to mbox files as + root, so this "optional" parameter is required in that situation. + * locktype (string) — which type of file locking to use; may be + "lockf" (for fcntl locking) or "flock". The default in getmail + 4.7.0 and later is lockf. + +MDA_external + + MDA_external delivers messages by running an external program (known as + a message delivery agent, or MDA) and feeding it the message on its + standard input. Some typical MDAs include maildrop and procmail. + + The MDA_external destination takes one required parameter: + * path (string) — the path to the command to run. This value will be + expanded for leading ~ or ~USER and environment variables in the + form $VARNAME or ${VARNAME}. + + The MDA_external destination also takes several optional parameters: + * arguments (tuple of quoted strings) — arguments to be supplied to + the command. The following substrings will be substituted with the + equivalent values from the message: + + %(sender) — envelope return-path address + If the message is retrieved with a multidrop retriever class, the + message recipient (and parts of it) are also available with the + following replacement substrings: + + %(recipient) — envelope recipient address + + %(local) — local-part of the envelope recipient address + + %(domain) — domain-part of the envelope recipient address + + %(mailbox) — the IMAP mailbox name the message was retrieved + from; for POP, this will be empty + The default value of the arguments parameter is (), so no arguments + are supplied to the command. + * unixfrom (boolean) — whether to include a Unix-style mbox From_ + line at the beginning of the message supplied to the command. + Defaults to false. Some MDAs expect such a line to be present and + will fail to operate if it is missing. + * user (string) — if supplied, getmail will change the effective UID + to that of the named user. Note that this typically requires root + privileges. + * group (string) — if supplied, getmail will change the effective GID + to that of the named group. Note that this typically requires root + privileges. + * allow_root_commands (boolean) — if set, getmail will run external + commands even if it is currently running with root privileges. The + default is false, which causes getmail to raise an exception if it + is asked to run an external command as root. Note that setting this + option has serious security implications. Don't use it if you don't + know what you're doing. I strongly recommend against running + external processes as root. + * ignore_stderr (boolean) — if set, getmail will not consider it an + error if the program writes to stderr. The default is false, which + causes getmail to consider the delivery failed and leave the + message on the server, proceeding to the next message. This + prevents loss of mail if the MDA writes to stderr but fails to exit + nonzero when it encounters an error. Note that setting this option + has serious implications; some MDAs can fail to deliver a message + but still exit 0, which can cause loss of mail if this option is + set. Only change this setting if you are confident your MDA always + exits nonzero on error. + + A basic invocation of an external MDA might look like this: +[destination] +type = MDA_external +path = /path/to/mymda +arguments = ("--log-errors", ) + + Something more complex might look like this: +[destination] +type = MDA_external +path = /path/to/mymda +# Switch to fred's UID and the mail group GID before delivering his mail +user = fred +group = mail +arguments = ("--strip-forbidden-attachments", "--recipient=%(recipient)") + +MultiDestination + + MultiDestination doesn't do any message deliveries itself; instead, it + lets you specify a list of one or more other destinations which it will + pass each message to. You can use this to deliver each message to + several different destinations. + + The MultiDestination destination takes one required parameter: + * destinations (tuple of quoted strings) — the destinations which the + messages will be passed to. A destination is a string that refers + to another configuration file section by name (shortcuts for + maildirs and mboxrd files are also provided; see below), like this: +destinations = ('[other-destination-1]', '[other-destination-2]') + +[other-destination-1] +type = Mboxrd +path = /var/spool/mail/alice +user = alice + +[other-destination-2] +type = Maildir +path = /home/joe/Maildir/ +user = joe + + Because Maildir and Mboxrd destinations are common, you can specify + them directly as a shortcut if they do not require a user + parameter. If the string (after expansion; see below) starts with a + dot or slash and ends with a slash, it specifies the path of a + Maildir destination, while if it starts with a dot or a slash and + does not end with a slash, it specifies the path of a Mboxrd + destination. + For instance, you can deliver mail to two maildirs with the + following: +destinations = ('~/Mail/inbox/', '~/Mail/archive/current/') + + Each destination string is first expanded for leading ~ or ~USER + and environment variables in the form $VARNAME or ${VARNAME}. + + Some examples: + * To deliver to a maildir named Maildir in the home directory of user + jeff, when getmail is run as that user: +[destination] +type = MultiDestination +destinations = ("~jeff/Maildir/", ) + + * To deliver to an mboxrd file: +[destination] +type = MultiDestination +destinations = ("/var/spool/mail/alice", ) + + * To deliver with an external MDA: +[destination] +type = MultiDestination +destinations = ("[procmail-as-bob]", ) + +[procmail-as-bob] +type = MDA_external +path = /path/to/procmail +arguments = ('~bob/.procmailrc', '-f', '%(sender)') +user = bob + + Of course, the whole point of MultiDestination is to allow you to + specify multiple destinations, like this: +[destination] +type = MultiDestination +destinations = ( + "~jeff/Mail/inbox", + "[procmail-as-jeff]", + "/var/mail-archive/incoming" + ) + +[procmail-as-jeff] +type = MDA_external +path = /path/to/procmail +arguments = ('~jeff/.procmailrc', '-f', '%(sender)') +user = jeff + +MultiSorter + + MultiSorter compares the envelope recipient address of messages against + a list of user-supplied regular expressions and delivers the message to + the destination (maildir, mboxrd file, or other) associated with any + matching patterns. A message can match multiple patterns and therefore + be delivered to multiple matching destinations. Any message which + matches none of the patterns is delivered to a default destination for + the postmaster. + + Because MultiSorter requires the envelope recipient to operate, it must + be used with a domain mailbox retriever. If you instead want to do some + basic message sorting based on getmail's best guess as to the envelope + recipient of the message, see the MultiGuesser destination class below. + + The MultiSorter destination takes one required parameter: + * default (string) — the destination for messages which aren't + matched by any of the "locals" regular expressions. The destination + can be a maildir, mboxrd file, or other destination. See + MultiDestination for an explanation of how the type of destination + is interpreted from this value. + + The MultiSorter destination also takes one optional parameter: + * locals (tuple of 2-tuples) — zero or more regular expression – + destination pairs. Messages will be delivered to each destination + for which the envelope recipient matches the given regular + expression. The regular expression and destination are supplied as + two quoted strings in a tuple; locals is then a tuple of such pairs + of strings. Destinations are specified in the same manner as with + the "default" parameter, above. + + Important note: if your regular expression contains backslashes (by + themselves, or as part of an escaped character or symbol like \n or \W + ), you need to tell the parser that this expression must be parsed + "raw" by prepending the string with an "r": +locals = ( + (r'jeff\?\?\?@.*', '[jeff]'), + ('alice@', '[alice]') + ) + +locals = ( + ('jeff@.*', '[jeff]'), + (r'alice\D+@', '[alice]') + ) + + Note that if you don't understand regular expressions, you don't need + to worry about it. In general, an email address is a regular expression + that matches itself. The only significant times this isn't the case is + when the address contains odd punctuation characters like ^, $, \, or + [. Handy hints: + * the regular expression . (dot) matches anything + * matches can occur anywhere in the address. If you want to only + match at the beginning, start your expression with the ^ character. + If you only want to match the whole address, also end your + expression with a dollar sign $. + + Using regular expressions: + * The regular expression joe@example.org matches the addresses + joe@example.org, joe@example.org.net, and heyjoe@example.org. + * The regular expression ^jeff@ matches the addresses + jeff@example.org and jeff@example.net, but not + otherjeff@example.org. + * The regular expression sam matches the addresses sam@example.org, + samantha@example.org, asam@example.org, and chris@isam.example.net. + + Some examples: + * + + Deliver mail matching jeff@example.net to ~jeff/Maildir/ + + Deliver mail matching alice@anything to ~alice/inbox + + Deliver all other mail to ~bob/Maildir/ +[destination] +type = MultiSorter +default = [bob-default] +locals = ( + ('jeff@example.net', '[jeff]'), + ('alice@', '[alice]') + ) + +[jeff] +type = Maildir +path = ~jeff/Maildir/ +user = jeff + +[alice] +type = Mboxrd +path = ~alice/inbox +user = alice + +[bob-default] +type = Maildir +path = ~bob/Maildir/ +user = bob + + * + + Deliver mail for jeff, bob, and alice to maildirs in their + home directories + + Deliver copies of all messages to samantha's mail archive + + Deliver copies of all messages to a program that logs certain + information. This program should run as the user log, and + command arguments should tell it to record the info to + /var/log/mail/info +[destination] +type = MultiSorter +default = doesn't matter, this won't be used, as locals will always match +locals = ( + ('^jeff@', '[jeff]'), + ('^bob@', '[bob]'), + ('^alice@', '[alice]'), + ('.', '[copies]'), + ('.', '[info]') + ) + +[alice] +type = Maildir +path = ~alice/Maildir/ +user = alice + +[bob] +type = Maildir +path = ~bob/Maildir/ +user = bob + +[jeff] +type = Maildir +path = ~jeff/Maildir/ +user = jeff + +[copies] +type = Maildir +path = ~samantha/Mail/archive/copies/ +user = samantha + +[info] +type = MDA_external +path = /path/to/infologger +arguments = ('--log=/var/log/mail/info', '--sender=%(sender)', '--recipient=%(re +cipient)) +user = log + +MultiGuesser + + MultiGuesser tries to guess what the envelope recipient address of the + message might have been, by comparing addresses found in the message + header against a list of user-supplied regular expressions, and + delivers the message to the destination (maildir, mboxrd file, or + other) associated with any matching patterns. A message can match + multiple patterns and therefore be delivered to multiple matching + destinations. Any message which matches none of the patterns is + delivered to a default destination for the postmaster. In this fashion, + you can do basic mail filtering and sorting with getmail without using + an external filtering message delivery agent (MDA) (such as maildrop or + procmail), if and only if the message recipient is the criteria you + want to filter on. + + If you want to filter based on arbitrary message critera, like "What + address is in the To: header field?" or "Who is the message from?", + then use the filtering MDA of your choice, called from a getmail + MDA_external destination. + + MultiGuesser is similar to MultiSorter, except that it does not operate + on the true envelope recipient address, and therefore does not require + a domain mailbox retriever. Because it is "guessing" at the intended + recipient of the message based on the contents of the message header, + it is fallible — for instance, the address of a recipient of a mailing + list message may not appear in the header of the message at all. If + your locals regular expression patterns are only looking for that + address, MultiGuesser will then have to deliver it to the destination + specified as the default recipient. + + This functionality is very similar to the guessing functionality of + getmail version 2, which was removed in version 3. MultiGuesser + extracts a list of addresses from the message header like this: + 1. it looks for addresses in any Delivered-To: header fields. + 2. if no addresses have been found, it looks for addresses in any + Envelope-To: header fields. + 3. if no addresses have been found, it looks for addresses in any + X-Envelope-To: header fields. + 4. if no addresses have been found, it looks for addresses in any + Apparently-To: header fields. + 5. if no addresses have been found, it looks for addresses in any + Resent-to: or Resent-cc: header fields (or Resent-bcc:, which + shouldn't be present). + 6. if no addresses have been found, it looks for addresses in any To: + or cc: header fields (or bcc:, which shouldn't be present). + + The MultiGuesser destination takes one required parameter: + * default (string) — see MultiSorter for definition. + + The MultiGuesser destination also takes one optional parameter: + * locals (tuple of 2-tuples) — see MultiSorter for definition. + + Examples: + + If you have a simple POP3 account (i.e. it's not a multidrop mailbox) + and you want to deliver your personal mail to your regular maildir, but + deliver mail from a couple of mailing lists (identified by the list + address appearing in the message header) to separate maildirs, you + could use a MultiGuesser configuration like this: +[destination] +type = MultiGuesser +default = ~/Maildir/ +locals = ( + ("list-address-1@list-domain-1", "~/Mail/mailing-lists/list-1/"), + ("list-address-2@list-domain-2", "~/Mail/mailing-lists/list-2/"), + ) + + See MultiSorter above for other examples of getmail rc usage; the only + difference is the type parameter specifying the MultiGuesser + destination. + +MDA_qmaillocal + + MDA_qmaillocal delivers messages by running the qmail-local program as + an external MDA. qmail-local uses .qmail files to tell it what to do + with messages. If you're not already familiar with qmail, you don't + need to use this destination class. + + The MDA_qmaillocal destination takes several optional parameters: + * qmaillocal (string) — path to the qmail-local program. The default + value is /var/qmail/bin/qmail-local. + * user (string) — supplied to qmail-local, and also tells getmail to + change the current effective UID to that of the named user before + running qmail-local. Note that this typically requires root + privileges. The default value is the account name of the current + effective UID. + * group (string) — if supplied, getmail will change the effective GID + to that of the named group before running qmail-local. Note that + this typically requires root privileges. + * homedir (string) — supplied to qmail-local. The default value is + the home directory of the account with the current effective UID. + * localdomain (string) — supplied to qmail-local as its domain + argument. The default value is the fully-qualified domain name of + the local host. + * defaultdelivery (string) — supplied to qmail-local as its + defaultdelivery argument. The default value is ./Maildir/. + * conf-break (string) — supplied to qmail-local as its dash argument. + The default value is -. + * localpart_translate (2-tuple of quoted strings) — if supplied, the + recipient address of the message (which is used to construct the + local argument (among others) to qmail-local) will have any leading + instance of the first string replaced with the second string. This + can be used to remap recipient addresses, trim extraneous prefixes + (such as the qmail virtualdomain prepend value), or perform other + tasks. The default value is ('', '') (i.e., no translation). + * strip_delivered_to (boolean) — if set, Delivered-To: header fields + will be removed from the message before handing it to qmail-local. + This may be necessary to prevent qmail-local falsely detecting a + looping message if (for instance) the system retrieving messages + otherwise believes it has the same domain name as the retrieval + server. Inappropriate use of this option may cause message loops. + The default value is False. + * allow_root_commands (boolean) — if set, getmail will run + qmail-local even if it is currently running with root privileges. + The default is false, which causes getmail to raise an exception if + it is asked to run an external command as root. Note that setting + this option has serious security implications. Don't use it if you + don't know what you're doing. I strongly recommend against running + external processes as root. + + A basic invocation of qmail-local might look like this: +[destination] +type = MDA_qmaillocal +user = joyce + + Something more complex might look like this: +[destination] +type = MDA_qmaillocal +user = joyce +# The mail domain isn't the normal FQDN of the server running getmail +localdomain = host.example.net +# Trim the server's virtualdomain prepend value from message recipient before +# sending it to qmail-local +localpart_translate = ('mailhostaccount-', '') + +Creating the [options] section + + The optional options section of the rc file can be used to alter + getmail's default behaviour. The parameters supported in this section + are as follows: + * verbose (integer) — controls getmail's verbosity. If set to 2, + getmail prints messages about each of its actions. If set to 1, it + prints messages about retrieving and deleting messages (only). If + set to 0, getmail will only print warnings and errors. Default: 1. + * read_all (boolean) — if set, getmail retrieves all available + messages. If unset, getmail only retrieves messages it has not seen + before. Default: True. + * delete (boolean) — if set, getmail will delete messages after + retrieving and successfully delivering them. If unset, getmail will + leave messages on the server after retrieving them. Default: False. + * delete_after (integer) — if set, getmail will delete messages this + number of days after first seeing them, if they have been retrieved + and delivered. This, in effect, leaves messages on the server for a + configurable number of days after retrieving them. Note that the + delete parameter has higher priority; if both are set, the messages + will be deleted immediately. Default: 0, which means not to enable + this feature. + * delete_bigger_than (integer) — if set, getmail will delete messages + larger than this number of bytes after retrieving them, even if the + delete and delete_after options are disabled. The purpose of this + feature is to allow deleting only large messages, to help keep a + mailbox under quota. Has no effect if delete is set, as that will + unconditionally remove messages. If delete_after is also set, the + message will be deleted immediately after retrieval if it is over + this size, and otherwise will be deleted according to the setting + of delete_after. Default: 0, which means not to enable this + feature. + * max_bytes_per_session (integer) — if set, getmail will retrieve + messages totalling up to this number of bytes before closing the + session with the server. This can be useful if you do not want + large messages causing large bursts of network traffic. Default: 0, + which means not to enable this feature. Note that message sizes + reported by the server are used, and therefore may vary slightly + from the actual size on disk after message retrieval. + * max_message_size (integer) — if set, getmail will not retrieve + messages larger than this number of bytes. Default: 0, which means + not to enable this feature. + * max_messages_per_session (integer) — if set, getmail will process a + maximum of this number of messages before closing the session with + the server. This can be useful if your network or the server is + particuarly unreliable. Default: 0, which means not to enable this + feature. + * delivered_to (boolean) — if set, getmail adds a Delivered-To: + header field to the message. If unset, it will not do so. Default: + True. Note that this field will contain the envelope recipient of + the message if the retriever in use is a multidrop retriever; + otherwise it will contain the string "unknown". + * received (boolean) — if set, getmail adds a Received: header field + to the message. If unset, it will not do so. Default: True. + * message_log (string) — if set, getmail will record a log of its + actions to the named file. The value will be expanded for leading ~ + or ~USER and environment variables in the form $VARNAME or + ${VARNAME}. Default: '' (the empty string), which means not to + enable this feature. + * message_log_syslog (boolean) — if set, getmail will record a log of + its actions using the system logger. Note that syslog is inherently + unreliable and can lose log messages. Default: False. + * message_log_verbose (boolean) — if set, getmail will log to the + message log file (or syslog) information about messages not + retrieved and the reason for not retrieving them, as well as + starting and ending information lines. By default, it will log only + about messages actually retrieved, and about error conditions. Note + that this has no effect if neither message_log nor + message_log_syslog is in use. Default: False. + + Most users will want to either enable the delete option (to delete mail + after retrieving it), or disable the read_all option (to only retrieve + previously-unread mail). + + The verbose, read_all, and delete parameters can be overridden at run + time with commandline options. + +[options] example + + To configure getmail to operate quietly, to retrieve only new mail, to + delete messages after retrieving them, and to log its actions to a + file, you could provide the following in your getmail rc file(s): +[options] +verbose = 0 +read_all = false +delete = true +message_log = ~/.getmail/log + +Creating the [filter-something] sections + + The filter-something section(s) of the rc file (which are not required) + tell getmail to process messages in some way after retrieving them, but + before delivering them to your destinations. Filters can tell getmail + to drop a message (i.e. not deliver it at all), add information to the + message header (i.e. for a spam- classification system or similar), or + modify message content (like an antivirus system stripping suspected + MIME parts from messages). + + You can specify any number of filters; provide a separate rc file + section for each, naming each of them filter-something. They will be + run in collated order, so it's likely simplest to name them like this: + * [filter-1] + * [filter-2] + * [filter-3] + + Begin with the section header line as follows: +[filter-something] + + Then, include a type string parameter to tell getmail what type of + filter. The possible values are: + * Filter_classifier — run the message through an external program, + and insert the output of the program into + X-getmail-filter-classifier: header fields in the message. Messages + can be dropped by having the filter return specific exit codes. + * Filter_external — supply the message to an external program, which + can then modify the message in any fashion. The program must print + the modified message to stdout. getmail reads the modified message + from the program in this fasion before proceeding to the next + filter or destination. Messages can be dropped by having the filter + return specific exit codes. + * Filter_TMDA — run the message through the tmda-filter program for + use with the Tagged Message Delivery Agent (TMDA) package. If + tmda-filter returns 0, the message will be passed to the next + filter (or destination). If it returns 99, the message will be + dropped, and TMDA is responsible for sending a challenge message, + queuing the original, etc., as with normal TMDA operation in a + .qmail, .courier, or .forward file. + + By default, if a filter writes anything to stderr, getmail will + consider the delivery to have encountered an error. getmail will leave + the message on the server and proceed to the next message. You must + configure any filter you use not to emit messages to stderr except on + errors — please see the documentation for your filter program for + details. Optionally, if you know your filter can emit warnings on + stderr under non-error conditions, you can set the ignore_stderr + option. + +Filter_classifier + + Filter_classifier runs the message through an external program, placing + the output of that program into X-getmail-filter-classifier: header + fields. It can also cause messages to be dropped by exiting with a + return code listed in the exitcodes_drop parameter. + + Filter_classifier has one required parameter: + * path (string) — the path to the command to run. This value will be + expanded for leading ~ or ~USER and environment variables in the + form $VARNAME or ${VARNAME}. + + In addition, Filter_classifier takes the following optional parameters: + * arguments (tuple of quoted strings) — arguments to be supplied to + the command. The following substrings will be substituted with the + equivalent values from the message: + + %(sender) — envelope return-path address + If the message is retrieved with a multidrop retriever class, the + message recipient (and parts of it) are also available with the + following replacement substrings: + + %(recipient) — envelope recipient address + + %(local) — local-part of the envelope recipient address + + %(domain) — domain-part of the envelope recipient address + The default value of the arguments parameter is (), so no arguments + are supplied to the command. + * unixfrom (boolean) — whether to include a Unix-style mbox From_ + line at the beginning of the message supplied to the command. + Default: False. + * user (string) — if supplied, getmail will change the effective UID + to that of the named user. Note that this typically requires root + privileges. + * group (string) — if supplied, getmail will change the effective GID + to that of the named group. Note that this typically requires root + privileges. + * allow_root_commands (boolean) — if set, getmail will run external + commands even if it is currently running with root privileges. The + default is false, which causes getmail to raise an exception if it + is asked to run an external command as root. Note that setting this + option has serious security implications. Don't use it if you don't + know what you're doing. I strongly recommend against running + external processes as root. + * ignore_stderr (boolean) — if set, getmail will not consider it an + error if the filter writes to stderr. The default is false, which + causes getmail to consider the delivery failed and leave the + message on the server, proceeding to the next message. This + prevents loss of mail if the filter writes to stderr but fails to + exit nonzero when it encounters an error. Note that setting this + option has serious implications; some poorly-written programs + commonly used as mail filters can can mangle or drop mail but still + exit 0, their only clue to failure being warnings emitted on + stderr. Only change this setting if you are confident your filter + always exits nonzero on error. + * exitcodes_drop (tuple of integers) — if the filter returns an exit + code in this list, the message will be dropped. The default is (99, + 100). + * exitcodes_keep (tuple of integers) — if the filter returns an exit + code other than those in exitcodes_drop and exitcodes_keep, getmail + assumes the filter encountered an error. getmail will then not + proceed, so that the message is not lost. The default is (0, ). + +Filter_external + + Filter_external runs the message through an external program, and + replaces the message with the output of that program, allowing the + filter to make arbitrary changes to messages. It can also cause + messages to be dropped by exiting with a return code listed in the + exitcodes_drop parameter. + + Filter_external has one required parameter: + * path (string) — see Filter_classifier for definition. + + In addition, Filter_external takes the following optional parameters: + * arguments (tuple of quoted strings) — see Filter_classifier for + definition. + * unixfrom (boolean) — see Filter_classifier for definition. + * user (string) — see Filter_classifier for definition. + * group (string) — see Filter_classifier for definition. + * allow_root_commands (boolean) — see Filter_classifier for + definition. + * ignore_stderr (boolean) — see Filter_classifier for definition. + * exitcodes_drop (tuple of integers) — see Filter_classifier for + definition. + * exitcodes_keep (tuple of integers) — see Filter_classifier for + definition. + +Filter_TMDA + + Filter_external runs the message through the external program + tmda-filter, allowing the use of the Tagged Message Delivery Agent + (TMDA) package. As TMDA relies on the message envelope, this filter + requires the use of a multidrop retriever class to function. It sets + the three environment variables SENDER, RECIPIENT, and EXT prior to + running tmda-filter. + + I've tested this filter, and it Works For Me™, but I'm not a regular + TMDA user. I would appreciate any feedback about its use from TMDA + users. + + Filter_TMDA has no required parameters. It has the following optional + parameters: + * path (string) — the path to the tmda-filter binary. Default: + /usr/local/bin/tmda-filter. This value will be expanded for leading + ~ or ~USER and environment variables in the form $VARNAME or + ${VARNAME}. + * user (string) — see Filter_classifier for definition. + * group (string) — see Filter_classifier for definition. + * allow_root_commands (boolean) — see Filter_classifier for + definition. + * ignore_stderr (boolean) — see Filter_classifier for definition. + * conf-break (string) — this value will be used to split the + local-part of the envelope recipient address to determine the value + of the EXT environment variable. For example, if the envelope + sender address is sender-something@host.example.org, and the + envelope recipient address is user-ext-ext2@host.example.net, and + conf-break is set to -, getmail will set the environment variables + SENDER to "sender-something@host.example.org", RECIPIENT to + "user-ext-ext2@host.example.net", and EXT to "ext-ext2". Default: + "-". + +[filter-something] examples + + You might filter spam messages in your MUA based on information added + to the message header by a spam-classification program. You could have + that information added to the message header with a filter + configuration like this: +[filter-3] +type = Filter_classifier +path = /path/to/my-classifier +arguments = ('--message-from-stdin', '--report-to-stdout') +user = nobody + + You might use a program to prevent users from accidentally destroying + their data by stripping suspected attachments from messages. You could + have that information added to the message header with a filter + configuration like this: +[filter-3] +type = Filter_external +path = /path/to/my-mime-filter +arguments = ('--message-from-stdin', '--remove-all-but-attachment-types=text/pla +in,text/rfc822') +user = nobody + + You might use TMDA to challenge messages from unknown senders. If the + default parameters are fine for your configuration, this is as simple + as: +[filter-3] +type = Filter_TMDA + +getmail rc file examples + + Several examples of different getmail rc configuration are available in + the included file getmailrc-examples. + +Running getmail + + To use getmail, simply run the script getmail, which is typically + installed in /usr/local/bin/ by default. getmail will read the default + getmail rc file (getmailrc) from the default configuration/data + directory (~/.getmail/) and begin operating. + + You can modify this behaviour by supplying commandline options to + getmail. + +Commandline options + + getmail understands the following options: + * --version — show getmail's version number and exit + * --help or -h — show a brief usage summary and exit + * --getmaildir=DIR or -gDIR — use DIR for configuration and data + files + * --rcfile=FILE or -rFILE — read getmail rc file FILE instead of the + default. The file path is assumed to be relative to the getmaildir + directory unless this value starts with a slash (/). This option + can be given multiple times to have getmail retrieve mail from + multiple accounts. + * --dump — read rc files, dump configuration, and exit (debugging) + * --trace — print extended debugging information + + If you are using a single getmailrc file with an IMAP server that + understands the IDLE extension from RFC 2177, you can use the + --idle=MAILBOX option to specify that getmail should wait on the server + to notify getmail of new mail in the specified mailbox after getmail is + finished retrieving mail. + + In addition, the following commandline options can be used to override + any values specified in the [options] section of the getmail rc files: + * --verbose or -v — operate more verbosely. Can be given multiple + times. + * --quiet or -q — print only warnings or errors while running + * --delete or -d — delete messages after retrieving + * --dont-delete or -l — do not delete messages after retrieving + * --all or -a — retrieve all messages + * --new or -n — retrieve only new (unseen) messages + + For instance, if you want to retrieve mail from two different mail + accounts, create a getmail rc file for each of them (named, say, + getmailrc-account1 and getmailrc-account2) and put them in ~/.getmail/ + . Then run getmail as follows: +$ getmail --rcfile getmailrc-account1 --rcfile getmailrc-account2 + + If those files were located in a directory other than the default, and + you wanted to use that directory for storing the data files as well, + you could run getmail as follows: +$ getmail --getmaildir /path/to/otherdir --rcfile getmailrc-account1 --rcfile ge +tmailrc-account2 + +Using getmail as an MDA + + getmail includes helper scripts which allow you to use it to deliver + mail from other programs to maildirs or mboxrd files. + +Using the getmail_maildir MDA + + The getmail_maildir script can be used as an MDA from other programs to + deliver mail to maildirs. It reads the mail message from stdin, and + delivers it to a maildir path provided as an argument on the + commandline. This path must (after expansion by the shell, if + applicable) start with a dot or slash and end with a slash. + + getmail_maildir uses the contents of the SENDER environment variable to + construct a Return-Path: header field and the contents of the RECIPIENT + environment variable to construct a Delivered-To: header field at the + top of the message. + + getmail_maildir also accepts the options --verbose or -v which tell it + to print a status message on success. The default is to operate + silently unless an error occurs. + +Example + + You could deliver a message to a maildir named Maildir located in your + home directory by running the following command with the message on + stdin: +$ getmail_maildir $HOME/Maildir/ + +Using the getmail_mbox MDA + + The getmail_mbox script can be used as an MDA from other programs to + deliver mail to mboxrd-format mbox files. It reads the mail message + from stdin, and delivers it to an mbox path provided as an argument on + the commandline. This path must (after expansion by the shell, if + applicable) start with a dot or slash and not end with a slash. + + getmail_maildir uses the contents of the SENDER environment variable to + construct a Return-Path: header field and mbox From_ line and the + contents of the RECIPIENT environment variable to construct a + Delivered-To: header field at the top of the message. + + getmail_mbox also accepts the options --verbose or -v which tell it to + print a status message on success. The default is to operate silently + unless an error occurs. + +Example + + You could deliver a message to an mboxrd-format mbox file named inbox + located in a directory named mail in your home directory by running the + following command with the message on stdin: +$ getmail_mbox $HOME/mail/inbox + +Using getmail_fetch to retrieve mail from scripts + + getmail includes the getmail_fetch helper script, which allows you to + retrieve mail from a POP3 server without the use of a configuration + file. It is primarily intended for use in automated or scripted + environments, but can be used to retrieve mail normally. + + See the getmail_fetch manual page for details on the use of + getmail_fetch.

@@ -0,0 +1,469 @@ +getmail documentation + + This is the documentation for getmail version 4. Version 4 includes + numerous changes from version 3.x; if you are using getmail version 3, + please refer to the documentation included with that version of the + software. + + getmail is Copyright © 1998-2009 Charles Cazabon. <charlesc-getmail @ + pyropus.ca> + + getmail is licensed under the GNU General Public License version 2 + (only). If you wish to obtain a license to distribute getmail under + other terms, please contact me directly. + +Table of Contents + + * getmail documentation + * + + getmail documentation + + + o Features + o Differences from previous versions + o Requirements + o Obtaining getmail + o Installing getmail + o + # For the impatient + # Full installation instructions + # Installing from the RPM + # Installing directly from the source + # + @ Installing in the default location + @ Installing under an alternate prefix directory + @ Installing parts of the package to alternate + directories + # Installing the getmailcore package in a non-standard + location + # Building a binary package from the source + o getmail mailing lists + o + # getmail-users' mailing list + # + @ How to subscribe + @ How to unsubscribe + @ How to post + @ Archives of the getmail-users' mailing list + @ Notes on the getmail-users' mailing list + # Announcements List + # + @ How to subscribe + @ How to unsubscribe + @ How to post + @ Archives of the getmail announcements mailing + list + * getmail configuration + * + + Configuring getmail + + + o Creating a getmail rc file + + Running getmail + + + o Commandline options + o Using getmail as an MDA + o Using getmail_fetch to retrieve mail from scripts + * getmail troubleshooting + * + + Troubleshooting problems + + + o Error messages + o Warning messages + o Unexpected Behaviour + * getmail frequently-asked questions (FAQs) + * + + Frequently-Asked Questions (FAQs) + + + o About getmail + o Configuring getmail + o How do I … + o Using getmail with other software + o I think I found this bug in getmail … + +Features + + getmail is a mail retriever designed to allow you to get your mail from + one or more mail accounts on various mail servers to your local machine + for reading with a minimum of fuss. getmail is designed to be secure, + flexible, reliable, and easy-to-use. getmail is designed to replace + other mail retrievers such as fetchmail. + + getmail version 4 includes the following features: + * simple to install, configure, and use + * retrieve virtually any mail + + support for accessing mailboxes with the following protocols: + o POP3 + o POP3-over-SSL + o IMAP4 + o IMAP4-over-SSL + o SDPS (Demon UK's extensions to POP3) + + support for single-user and domain mailboxes + + retrieve mail from an unlimited number of mailboxes and + servers + + can remember which mail it has already retrieved, and can be + set to only download new messages + * support for message filtering, classification, and annotation by + external programs like spam filters and anti-virus programs + * support for delivering messages to different destinations based on + the message recipient + * reliability + + native safe and reliable delivery support for maildirs and + mboxrd files, in addition to delivery through arbitrary + external message delivery agents (MDAs) + + does not destroy information by rewriting mail headers + + does not cause mail loops by doing SMTP injection, and + therefore does not require that you run an MTA (like qmail or + sendmail) on your host + * written in Python, and therefore easy to extend or customize + + a flexible, extensible architecture so that support for new + mail access protocols, message filtering operations, or + destination types can be easily added + + cross-platform operation; getmail 4 should work on Unix/Linux, + Macintosh, and other platforms. Windows support available + under the free Cygwin package. + * winner of various software awards, including DaveCentral's "Best of + Linux" + +Differences from previous versions + + getmail version 4 has been completely rewritten. It is designed to + closely mimic the interface and user experience of getmail version 3, + but the new architecture necessitates some differences you will notice: + * the getmail rc file (configuration file) format has changed. If you + are upgrading from version 3, you will need to write a new + configuration file based on the contents of your old one. The new + file format resembles the old in many ways. Each account you + retrieve mail from will require a separate rc file, but getmail can + operate with multiple rc files simultaneously if you wish to + retrieve mail from multiple accounts. + * support for protocols other than POP3/SDPS. IMAP support is now + included, and other protocols can be added with relative ease. + * support for SSL-encrypted protocols. The included POP3 and IMAP + retriever classes are complemented by SSL-enabled counterparts. + * messages can be filtered or annotated by external programs like + spam filters and anti-Microsoft-worm programs. Filters can cause + messages to be dropped completely. + * a flexible, extensible architecture. Additional classes for + handling new mail protocols, filter types, or destination + mailstores can be added without needing to modify the main script + at all. Feel free to contact me if you need a custom retriever, + filter, or destination class written, or if you want commercial + support for getmail. + +Requirements + + getmail version 4 requires Python version 2.3.3 or later. If you have + only an earlier version of Python available, you can install the latest + version without disturbing your current version, or use getmail version + 3, which requires only Python version 1.5.2 or later. + + At the time of this writing, the current stable version of Python is + 2.3.4. You can download that version from the page at + http://www.python.org/2.3.4/ . Binary packages are available for + RPM-based Linux systems, or building Python from source is typically as + easy as unpacking the source tarball, and running the following + commands: +./configure +make +make install + + Since the above was written, Python 2.4 has been released. getmail 4 + will work with that version of Python as well. + + getmail 4 also requires that servers uniquely identify the messages + they provide (via the UIDL command) to getmail for full functionality. + Certain very old or broken POP3 servers may not be capable of this (I + have had only one report of such problems from among the tens of + thousands of people who have downloaded getmail 4 from my website and + from other archives), or may not implement the UIDL command at all, and + limited support is available for such servers via the + BrokenUIDLPOP3Retriever and BrokenUIDLPOP3SSLRetriever retriever + classes. + +Obtaining getmail + + Download getmail 4 from the official website main page at + http://pyropus.ca/software/getmail/ . + +Installing getmail + +For the impatient + + Installing getmail is very easy; just download the tarball + distribution, unpack it, change into the directory it unpacks into, and + run this command: +$ python setup.py install + + That's all there is to it. 99.9% of users don't need a special + package/port/etc. If you'd like more details on install options, keep + reading. + +Full installation instructions + + Once you have downloaded or otherwise obtained getmail, unpack it. On + GNU-ish Unix-like systems, this means: +$ tar xzf getmail-version.tar.gz + + On Macintosh systems, use a Zip-type archiver program to unpack the + tarball. + + On SystemV-like Unix systems, you may instead need to break this down + into two steps: +$ gunzip getmail-version.tar.gz +$ tar xf getmail-version.tar + + Then, change into the extracted getmail directory and start the build + process. The easiest installation method is to use the included + setup.py Python distutils script to build and install getmail directly. + Alternatively, you can build a binary package (i.e., an RPM or similar + managed software package) for your system from the source package and + install the resulting package, but the Python distutils support for + this is spotty at present. + +Installing from the RPM + + If you downloaded the RPM, you should be able to install it with the + following command: +$ rpm -ihv getmail-version-release.noarch.rpm + +Installing directly from the source + + To build and install directly from the included source, follow these + steps. +$ cd getmail-version +$ python setup.py build + + When that completes in a few seconds, become root and then install the + software. You can install in the default location, or specify an + alternate location to install the software, or specify alternate + directories for only part of the package. + +Installing in the default location + + To install in the default location, become user root and install with + the following commands: +$ su +enter root password +# python setup.py install + + This will, by default, install files into subdirectories under the + directory prefix, which is the directory that your Python installation + was configured to install under (typically /usr/local/ or /usr/, but + other values are sometimes used): + * the scripts getmail, getmail_fetch, getmail_maildir, and + getmail_mbox will be installed under prefix/bin/ + * the Python package getmailcore (which implements all the protocol–, + filter–, and destination-specific code for getmail, plus various + other bits) will be installed under the site-specific packages + directory of your Python library directory. This directory is + prefix/lib/python-python-version/site-packages/. + * The documentation directory getmail-getmail-version will be + installed under prefix/doc/ + * The manual pages for the four scripts will be installed under + prefix/man/ + + You can see a list of the default installation locations by running: +# python setup.py install --show-default-install-dirs + +Installing under an alternate prefix directory + + You can specify an alternate prefix directory by supplying the --prefix + option to the install command, like this: +# python setup.py install --prefix=path + + This will install the various parts of the package in subdirectories + like in the default installation (see the section Installing in the + default location above), but under your specified prefix directory. + These alternate installations allow you to install the software without + root privileges (say, by installing under $HOME/). Note, however, that + the getmailcore package will not be in the default Python module search + path if you do this; see the section Installing the getmailcore package + in a non-standard location if you use this option. + +Installing parts of the package to alternate directories + + If you only want to change the directory for some of the components, + use the following options: + * --install-lib=path specifies the directory the getmailcore package + is installed under (i.e., it will be installed as path/getmailcore + ). See the section Installing the getmailcore package in a + non-standard location if you use this option. + * --install-scripts=path specifies the directory the four scripts are + installed under (i.e., they will be installed directly in path/ ). + * --install-data=path specifies the directory the documentation is + installed under (i.e., the HTML and plaintext documentation will be + installed in the directory path/doc/getmail-getmail-version/, and + the man(1) pages will be installed in path/man/man1/. + + For example, if your Python installation is located under /usr/ because + it was installed as part of your OS, but you would like the getmail + scripts installed into /usr/local/bin/ instead of /usr/bin/, while + still letting the getmailcore package be installed under + /usr/lib/python-python-version/site-packages/, and the documentation + and man pages under /usr/doc/ and /usr/man/ you could use this command + to install: +# python setup.py --install-scripts=/usr/local/bin/ + + If you also wanted to locate the documentation and man pages under + /usr/local/ but still install the getmailcore package in the default + /usr/lib/python-python-version/site-packages/, you would instead use + this command to install: +# python setup.py --install-scripts=/usr/local/bin/ --install-data=/usr/local/ + +Installing the getmailcore package in a non-standard location + + Note: if you use one of the above methods to install the getmailcore + package into a directory other than the default, the four scripts + (getmail, getmail_fetch, getmail_maildir, and getmail_mbox) will almost + certainly be unable to locate the required files from the getmailcore + package, because they will not be in a directory in the standard Python + module search path. You will need to do one of the following to make + those files available to the scripts: + * set the environment variable PYTHONPATH to tell Python where to + find the appropriate modules. See the documentation at the + Python.org website for details. + Note that setting PYTHONPATH in $HOME/.profile (or equivalent) is + not sufficient -- for instance, cron runs jobs in a simpler + environment, ignoring $HOME/.profile, and getmail would therefore + fail when run as a user cron job. It is strongly recommended that + you install the Python library files in the site-packages directory + which Python provides for exactly this reason. + * modify the scripts to explicitly tell Python where you've installed + them. Insert a line like this: +sys.path.append('/path/to/installation-directory') + + containing the path to the directory you installed the getmailcore + directory in, somewhere below the line which reads +import sys + + and before the first line which references getmailcore . + +Building a binary package from the source + + To build a binary package from the included source, run the following + command from inside the unpacked getmail source. +$ cd getmail-version +$ python setup.py bdist --format=package-format + + The useful allowed values for package-format are: + * rpm — build a .noarch.rpm file which can then be installed with the + rpm package manager. + * pkgtool — build a package for the Sun Solaris pkgtool package + manager. + * sdux — build a package for the HP/UX swinstall software installer. + + Ideally, if you use this method, it will result in a "built + distribution" binary package in a subdirectory named dist which can + then be installed using the appropriate system-specific tool. If you + have problems with this process, please do not ask me for assistance; + ask your OS vendor or the comp.lang.python newsgroup. The + install-directory-from-source process above is the only one I can + support, and it should work on all platforms. + + You can discuss issues with building binary packages on the getmail + users' mailing list. + +getmail mailing lists + +getmail-users' mailing list + + A mailing list has been set up to discuss getmail. Only subscribers may + post to the list. + + The list is available for free getmail support from me and other users, + for discussions of bugs, configuration issues, documentation, and other + technical issues related to getmail. + +How to subscribe + + To subscribe to the list, send a blank email to <getmail-subscribe @ + lists.pyropus.ca> and follow the instructions in the message you + receive. Read and save the "welcome" message you receive when you + subscribe; it contains valuable instructions about how to use the list. + +How to unsubscribe + + To un-subscribe from the list, send a blank email from the same address + you subscribed with to <getmail-unsubscribe @ lists.pyropus.ca> and + follow the instructions in the message you receive. + +How to post + + Once you have subscribed to the list, you may post messages to the list + by sending them to <getmail @ lists.pyropus.ca>. Complete instructions + for using the list are sent to you when you subscribe. + + The list allows plaintext message bodies and plaintext attachments. Do + not attempt to send binary files (gzip, etc), HTML, or other types, as + they will be stripped from your message. + + Note: please ensure you have read the documentation and Frequently + Asked Questions, and browsed/searched the mailing list archives before + posting a question to the mailing list. + +Archives of the getmail-users' mailing list + + There are browsable archives of the list at + http://marc.theaimsgroup.com/?l=getmail&r=1&w=2 and + http://news.gmane.org/gmane.mail.getmail.user . The GMANE getmail + users' archive is also available via NNTP if you prefer to read it with + a newsreader, rather than a web browser. + +Notes on the getmail-users' mailing list + + When subscribing to the getmail users' mailing list, please note the + following: + * The mailing list software does not, and will not munge the + Reply-To: header of list messages. I encourage you to read and post + to the list using a good MUA that properly supports reply-to-list + and reply-to-author functionality. If your MUA lacks a + reply-to-list function, you'll need to manually ensure your + followup messages to the the list are actually directed to the list + submission address. + * The mailing list software does not munge the Subject: header of + list messages, so don't look for "[getmail-users]" or anything like + that. If you want your MUA to recognize list messages, there are a + number of header fields added to allow it to do so. + * Subscribing and unsubscribing from the list are both secure and + completely automatic. When you try to do either, the list manager + software will send you a special message you have to reply to to + finish the operation; this prevents others from subscribing you to + or unsubscribing you from the list without your permission. + * You must be a list subscriber to post messages to the list. + +Announcements List + + If you only want to be notified of new releases of getmail, an + announce-only list has been set up. The list is very low-volume; you + can expect to receive only a small number of messages per month. + + All announcements are sent to both lists, so there is no need to + subscribe to the announcements list if you are on the discussion list. + +How to subscribe + + To subscribe to the list, send a blank email to + <getmail-announce-subscribe @ lists.pyropus.ca> and follow the + instructions in the message you receive. Read and save the "welcome" + message you receive when you subscribe; it contains valuable + instructions about how to use the list. + +How to unsubscribe + + To un-subscribe from the list, send a blank email from the same address + you subscribed with to <getmail-announce-unsubscribe @ + lists.pyropus.ca> and follow the instructions in the message you + receive. + +How to post + + You cannot post messages directly to the announcements list. If you + feel you have an announcement regarding getmail which should be + distributed, send it to me and request that I send it to the + announcements list. + +Archives of the getmail announcements mailing list + + There is an archive of the announcements list at + http://news.gmane.org/gmane.mail.getmail.announce . The GMANE getmail + announcements archive is also available via NNTP if you prefer to read + it with a newsreader, rather than a web browser.

@@ -0,0 +1,1156 @@ +getmail documentation + + This is the documentation for getmail version 4. Version 4 includes + numerous changes from version 3.x; if you are using getmail version 3, + please refer to the documentation included with that version of the + software. + + getmail is Copyright © 1998-2009 Charles Cazabon. + + getmail is licensed under the GNU General Public License version 2 + (only). If you wish to obtain a license to distribute getmail under + other terms, please contact me directly. + +Table of Contents + + * getmail documentation + * + + getmail documentation + + + o Features + o Differences from previous versions + o Requirements + o Obtaining getmail + o Installing getmail + o getmail mailing lists + * getmail configuration + * + + Configuring getmail + + + o Creating a getmail rc file + + Running getmail + + + o Commandline options + o Using getmail as an MDA + o Using getmail_fetch to retrieve mail from scripts + * getmail troubleshooting + * + + Troubleshooting problems + + + o Error messages + o Warning messages + o Unexpected Behaviour + * getmail frequently-asked questions (FAQs) + * + + Frequently-Asked Questions (FAQs) + + + o About getmail + o + # What is getmail? + # What platforms/machines does getmail run on? + # + @ Does getmail run on MS Windows? + @ Does getmail run on Macintosh systems? + @ Does getmail require Unix/Linux? + # How can I get support for getmail? + # I think I found a bug! How do I report it? + # I have a neat idea for random feature "foo" … how do + I get you to implement it? + # Why won't you implement random feature "foo"? + # Does getmail support virus scanning of retrieved + messages? + # Does getmail support spam filtering of retrieved + messages? + # Does getmail support SSL? + # Does getmail rewrite mail headers when it retrieves + mail? + # Can I upgrade from getmail 3 to getmail 4? What + about my "oldmail" files? + # Why did you write getmail? Why not just use + fetchmail? + o Configuring getmail + o + # What is a "domain mailbox"? + # Do I have to run sendmail or another MTA to use + getmail? + # Will getmail deliver mail as root? + # What's a maildir? + # What's "mboxrd" format? + # What's this "envelope sender" and "envelope + recipient" stuff? + # + @ Message header vs. message envelope + @ Receiving messages without your address in the + message header + @ Responsibility for recording the message + envelope + @ How this relates to domain or multidrop + mailboxes + # This rc stuff seems complicated. Does it have to be? + o How do I … + o + # How do I retrieve mail from multiple accounts? + # How do I get getmail to deliver messages to + different mailboxes based on … + # How do I stop getmail adding a Delivered-To: header + to messages? + # How do I stop getmail adding a Received: header to + messages? + # How do I make getmail deliver messages by + re-injecting with SMTP? + # How do I create a maildir? + # How do I create an mboxrd file? + # How do I make getmail deliver messages to an mh + folder? + # How do I run getmail in "daemon" mode? + # How do I make getmail stop after retrieving X + messages so that the server actually flushes deleted + messages? + # How do I make getmail retrieve mail from Hotmail? + # I'm using getmail. How do I make it … + # + @ I'm running getmail from cron. How do I + temporarily stop it? + @ How do I stop multiple instances of getmail + from running at the same time? + o Using getmail with other software + o + # How do I use SpamAssassin with getmail? + # How do I use ClamAV with getmail? + # + @ Getting prettier output from ClamAV + # How do I use F-Prot with getmail? + # How do I use procmail with getmail? + # How do I use maildrop with getmail? + # How do I use TMDA with getmail? + # + @ How can I get Gmail labels with getmail? + o I think I found this bug in getmail … + o + # getmail doesn't download all my mail from Gmail … + # FutureWarning: %u/%o/%x/%X of negative int will + return a signed string in Python 2.4 and up + # AttributeError: 'module' object has no attribute + 'fsync' + # operation error (SimplePOP3Retriever: [...] does not + uniquely identify messages [...] see documentation + or use BrokenUIDLPOP3Retriever instead + # MemoryError on OS X + # MemoryError when using IMAP + +Frequently-Asked Questions (FAQs) + + The following questions about getmail are answered more-or-less + frequently. Please also read the unexpected behaviour section of the + troubleshooting document. + +About getmail + +What is getmail? + + getmail is a mail retriever with support for POP3, POP3-over-SSL, + IMAP4, IMAP4-over-SSL, and SDPS mail accounts. It supports normal + single-user mail accounts and multidrop (domain) mailboxes. getmail is + written in Python, and licensed under the GNU General Public License + version 2. + +What platforms/machines does getmail run on? + + getmail runs on basically any platform. It's designed to, and written + in a language that helps to maintain cross-platform compatibility. + getmail is known to run on the following platforms: + * Linux-based GNU systems (all distributions) + * HURD-based GNU systems + * FreeBSD + * OpenBSD + * NetBSD + * HP/UX + * Sun Solaris + * IBM AIX + * Digital/Compaq Tru64 (a.k.a OSF/1) UNIX + * SGI Irix + * other commercial Unices + * Digital VMS / OpenVMS + * BeOS + * Amiga OS + * OS/2 + * Cygwin on Windows + * Macintosh OS X + * Macintosh OS 9 + + But getmail will also run on other, less common platforms. The only + real requirement is that Python run on that platform, and porting + Python is generally very easy. + +Does getmail run on MS Windows? + + Yes, under the free Cygwin package. Running recent versions of Python + under Cygwin requires a process known as "rebasing" your Cygwin + installation; you can find details in this Python developers' mailing + list message. + +Does getmail run on Macintosh systems? + + Yes. + +Does getmail require Unix/Linux? + + No. + +How can I get support for getmail? + + getmail is Free Software. As such, it comes with no warranty. However, + I will do my best to support getmail on a voluntary basis through the + getmail mailing list. + + If you are using getmail in a commercial or other environment where + problems cost money, consider contacting me privately for commercial + support, by emailing <charlesc-getmail-support @ pyropus.ca> + + If you have questions about getmail, the first step is to read the + documentation, and the remainder of the Frequently Asked Questions. If + your question isn't answered there, search the getmail mailing list + archives. + + If you still haven't found an answer to your question, please subscribe + to the getmail users' mailing list by sending a blank email to + <getmail-subscribe @ lists.pyropus.ca>. If you post your question + there, I will see it. As an additional bonus, your question may be + answered by another member of the list. + +I think I found a bug! How do I report it? + + First, make sure that you are running the latest version. You can + always find what is the latest version by checking this page at the + original web site: + http://pyropus.ca/software/getmail/. + If you running an older version of the software, chances are whatever + bug you may have found has already been fixed. + + Ideally, you should join the mailing list and send your bug report + there. You should include the following information: + * getmail version + * Python version + * any error message which getmail displayed + * the output from running getmail with your normal options plus + --dump + * if your problem is getmail not determining the proper local + recipient, please include the output of running getmail with your + normal options plus --trace, showing the retrieval of one + problematic message. + + If you absolutely cannot sign up for the mailing list, send the report + to me directly at <charlesc-getmail-bugs @ pyropus.ca>. I may not be + able to respond to all reports privately, but I will try to address any + bugs I find out about this way. + +I have a neat idea for random feature "foo" … how do I get you to implement +it? + + Follow the same instructions as for reporting bugs above — yes, that + means I would prefer you submit your idea to the getmail users' mailing + list. That will lead to a useful discussion if your feature has not + been proposed before. + +Why won't you implement random feature "foo"? + + Every line of code added to getmail has a certain cost. Every feature + added requires code, documentation, and support. Adding features + increases the complexity of the software, confuses users, and leads to + higher support costs. I therefore weigh features very carefully as a + cost-versus-benefit tradeoff before deciding whether to add them. + + Some users are confused by this. They think that a feature you don't + use has no cost, and therefore if it has any value to anyone, it should + be added. That simply isn't the case; the costs of an unused feature + are simply borne by others, including me. + + If you have asked me to add some feature, and I've said no, this may be + the reason. Other possibilities include me simply not having had + sufficient time to implement it yet. + +Does getmail support virus scanning of retrieved messages? + + Yes. You can use getmail message filtering options to do this with an + external virus scanning program, or invoke your virus scanning program + during delivery with getmail's support for external MDAs. + + Also see the FAQ about using getmail with the ClamAV program. + +Does getmail support spam filtering of retrieved messages? + + Yes. You can use getmail message filtering options to do this with an + external spam filtering program, or invoke your spam filtering program + during delivery with getmail's support for external MDAs. + + Also see the FAQ about using getmail with the SpamAssassin program. + +Does getmail support SSL? + + Yes. getmail has built in support for POP3-over-SSL and IMAP4-over-SSL. + +Does getmail rewrite mail headers when it retrieves mail? + + No. Rewriting message header fields is bad for many reasons; the + biggest problem is that it causes a loss of critical technical + information necessary to track down many mail problems. getmail will + add a new Received: header field and a new Delivered-To: header field, + but does not rewrite existing headers. You can disable the creation of + these header fields. + +Can I upgrade from getmail 3 to getmail 4? What about my "oldmail" files? + + Yes. getmail version 4 uses exactly the same + oldmail-server-port-username naming convention for its oldmail files. + The only difference is that version 4 escapes a couple of additional + characters in this string so that it is truly cross-platform + compatible. If you upgrade from version 3 to version 4, getmail will + still remember which messages you've already retrieved. + + To upgrade, do the following: + 1. Rename your old getmail rc file, creating a new file in + ~/.getmail/getmailrc. + 2. Create a new [options] section, containing the appropriate values + from your version 3 rc file [defaults] section. + 3. Create a new [retriever] section, using your previous server + configuration values in a new type = SimplePOP3Retriever or type = + MultidropPOP3Retriever as appropriate. + 4. Create a new [destination] section, using your previous destination + path values in a new type = Maildir, type = Mboxrd, type = + MDA_external, or type = MultiSorter destination as appropriate. + 5. If you were retrieving messages from multiple mail accounts in a + single version 3 getmail rc file, split them up into one account + per version 4 rc file. + + That's it. + +Why did you write getmail? Why not just use fetchmail? + + Short answer: … well, the short answer is mostly unprintable. The long + answer is … well, long: + + I do not like some of the design choices which were made with + fetchmail. getmail does things a little differently, and for my + purposes, better. In addition, most people find getmail easier to + configure and use than fetchmail. Perhaps most importantly, getmail + goes to great lengths to ensure that mail is never lost, while + fetchmail (in its default configuration) frequently loses mail, causes + mail loops, bounces legitimate messages, and causes many other + problems. + + When people have pointed out problems in fetchmail's design and + implementation, it's maintainer has frequently ignored them, or (worse + yet) gone in the completely wrong direction in the name of "fixing" the + problems. For instance, fetchmail's configuration file syntax has been + criticized as being needlessly difficult to write; instead of cleaning + up the syntax, the maintainer instead included a GUI + configuration-file-writing program, leading to comments like: + + The punchline is that fetchmail sucks, even if it does have + giddily-engineered whizbang configurator apps. + + As an example, Dan Bernstein, author of qmail and other software + packages, once noted to the qmail list: + + Last night, root@xxxxxxxxxxxxxxxxx reinjected thirty old messages + from various authors to qmail@xxxxxxxxxxxxxx + + This sort of idiocy happens much more often than most subscribers + know, thanks to a broken piece of software by Eric Raymond called + fetchmail. Fortunately, qmail and ezmlm have loop-prevention + mechanisms that stop these messages before they are distributed to + subscribers. The messages end up bouncing to the wrong place, thanks + to another fetchmail bug, but at least the mailing list is + protected. + + --D. J. Bernstein + + The maintainer also ignored dozens of complaints about fetchmail's + behaviour, stating (by fiat) that fetchmail was bug-free and had + entered "maintenance mode", allowing him to ignore further bug reports. + + fetchmail's default configuration values frequently cause lost or + misdirected mail, and seem to be chosen to cause maximum pain and + inconvenience. From fetchmail's to-do file (emphasis mine): + + Maybe refuse multidrop configuration unless "envelope" is + _explicitly_ configured … This would prevent a significant class of + shoot-self-in-foot problems. + + perhaps treat a delivery as "temporarily failed" … This is so you + don't lose mail if you configure the wrong envelope header. + + fetchmail is famous for mangling messages it retrieves, rather than + leaving them alone as a mail-handling program should. getmail will add + trace information to messages (so you can see what happened, and when), + but will otherwise leave message content alone. + + In addition, fetchmail has a long history of security problems: + * versions released before 20 June 2001 contain a buffer overflow, + which can be remotely exploited (see www.securityfocus.com/bid/2877 + for details). getmail is not vulnerable to buffer overflows, + because buffers in Python are dynamically sized. + * Another remotely-exploitable security hole discovered in fetchmail + in June 2002; versions prior to 5.9.10 (released in June 2002) are + exploitable . + * Reading fetchmail's UPDATES file, it appears that another security + problem was fixed in 5.9.12, where a server could crash fetchmail + on 64-bit platforms. Also worrying is a mention that it includes a + fix for "password shrouding". + * Another remotely-exploitable security hole in fetchmail discovered + in September 2002; this hole lets an attacker run arbitrary code on + the victim's computer. + * Another remotely-exploitable security hole in fetchmail discovered + in December 2002; once again, a remote attacker can run arbitrary + code on the machine running fetchmail in its default configuration. + See this advisory for details. + * January 2003: More buffer overflows in fetchmail let attackers run + arbitrary code . + * October 2003: Anyone can cause fetchmail to crash by sending you a + message . Other problems are here , and I might have missed some . + * Just in case you thought fetchmail was all better now, there's + still new security problems being discovered in it. In December, + 2005, it was revealed that anyone can send a fetchmail multidrop + user a message that causes fetchmail to crash. + + In July, 2004, it was noted that there may be at least 2 unfixed + denial-of-service attacks, 2 unfixed remote-code-execution, 2 unfixed + remote-user-access, and 3 unfixed remote-shell attacks against + fetchmail. See + http://www.mail-archive.com/euglug@euglug.org/msg00971.html for details + + I've given up even trying to stay abreast of the various security holes + in fetchmail, but others have noted continuing problems, including: + * another arbitrary code execution vulnerability announced on 21 July + 2005. + + The fetchmail authors' boneheaded decision to create a + configuration-file GUI editor (rather than actually giving fetchmail a + sane configuration syntax) also came back to bite them in the ass: in + October 2005, it became known that fetchmailconf created its files in + such a way that users' passwords could be read during file creation. + + Addendum, January 2007: since I wrote the above, the following new + security problems have been discovered in fetchmail: + * CVE-2005-4348 - anyone can crash fetchmail by sending messages + without headers + * CVE-2006-0321 - anyone can crash fetchmail by sending a message + that fetchmail tries to bounce + * CVE-2006-5867 - fetchmail can transmit passwords in plaintext even + if the user has configured it not to + * CVE-2006-5974 - anyone can cause fetchmail to crash by triggering + certain error code paths + + But don't just take my word for it; see + http://docs.freebsd.org/cgi/mid.cgi?200102172349.QAA11724 and + http://esr.1accesshost.com/ (note: went offline sometime in 2009 or + 2010; the content is still available at + http://web.archive.org/web/20080621090439/http://esr.1accesshost.com/ + ). + + getmail users have not had to worry about any of these security holes + or design and implementation errors. + +Configuring getmail + +What is a "domain mailbox"? + + A domain (or multidrop) mailbox is a POP3 mailbox which receives mail + for all users in a given domain. Normal mailboxes contain mail for a + single user (like jason@myisp.co.uk); some Internet Service Providers + which provide webhosting or other services will provide a POP3 mailbox + which receives mail for all addresses in a given domain (i.e. mail for + service@smallcompany.net, sales@smallcompany.net, and indeed anything + @smallcompany.net ends up in the same POP3 mailbox). + + getmail provides a method of retrieving mail from a domain mailbox and + distributing it among the various users automatically. The retriever + classes MultidropPOP3Retriever, MultidropPOP3SSLRetriever, + MultidropSDPSRetriever, MultidropIMAPRetriever, and + MultidropIMAPSSLRetriever provide this capability. + + See the documentation on the [retriever] section for details of what + the requirements for a multidrop mailbox are. getmail user Matthias + Andree also has a web page about multidrop mailboxes. + +Do I have to run sendmail or another MTA to use getmail? + + No. getmail delivers directly to maildirs, mboxrd files, or via + arbitrary MDAs, and never injects mail via SMTP, so no MTA is + necessary. + +Will getmail deliver mail as root? + + No. When run as the root user on a Unix-like system, getmail drops + privileges (switches to an unprivileged group and user id) before + delivering to maildirs or mboxrd files. You can specify the user + explicitly, or let getmail use the owner of the maildir or mboxrd file. + + If getmail attempts to deliver mail and finds it has UID 0 or GID 0, it + will refuse the delivery and print an error message. + +What's a maildir? + + A maildir is a mail storage format invented by D. J. Bernstein (author + of qmail) that requires no file locking to deliver to safely and + reliably, even over NFS. getmail natively supports delivery to + maildirs. + + See http://qmail.org/man/man5/maildir.html and + http://cr.yp.to/proto/maildir.html for details. + +What's "mboxrd" format? + + There are various sub-types of the mbox mail storage format. mboxrd is + the most reliable of them, though (like all mbox types) it still relies + on file locking and is therefore more easily corrupted than maildir + format. In particular, using mbox files with multiple writers over NFS + can be problematic. + + For details on the differences between the various mbox sub-types, see + http://qmail.org/man/man5/mbox.html. + +What's this "envelope sender" and "envelope recipient" stuff? + + The "envelope" of an email message is "message metadata"; that is, the + message is information, and the envelope is information about the + message (information about other information). Knowing this is critical + to understanding what a domain or multidrop mailbox is, how it works, + and what getmail can do for you. + + Others have tried to explain this with varying degrees of success. I'll + use the standard analogy of normal postal (i.e. non-electronic) mail: + +Message header vs. message envelope + + When you receive a letter (a reply from the customer-disservice + department of your telephone company, say) it arrives in an envelope. + You tear it open, remove the letter, and read it. At the top of the + letter is the telephone company's return address, followed by the date + the letter was written. Your name and mailing address follow that, and + then the remainder of the letter. + + The important thing to keep in mind is that the contents of the letter + (including the addresses just discussed) are never looked at by the + post office. If they can't deliver the letter (your mailing address on + the envelope got smudged in the rain), they'll return it to the address + listed in the top-left corner of the envelope. They don't check to make + sure that the address listed there is the same as the one listed at the + top of the letter. Similarly, when they can successfully deliver it, + they don't check to make sure that the recipient name and address on + the envelope matches the one listed on the letter between the date and + the salutation. + + The message header fields From: and Resent-from: are equivalent to the + block of address information at the top of the letter; it usually + contains the name and address of the sender of the message, but it is + never actually used in the delivery of the message. Similarly, the To:, + cc:, Resent-to:, and Resent-cc: header fields are the equivalent of the + block of address information between the date and the salutation on the + letter; they usually contain the names and addresses of the intended + recipients of the message, but they too are not used in the delivery of + the message. + +Receiving messages without your address in the message header + + You might open an envelope addressed to you and find that the letter + inside makes no mention of your name. Your name and address don't + appear anywhere in the letter, but it was still successfully delivered + to you based on the envelope information. There's nothing strange about + this. If someone else opens your mail for you, discards the envelopes, + and places the contents in your in-basket, you might wonder how some of + it ended up there, because there's nothing to connect you with the + message contents. + + Email is exactly like this. Each message has two parts, the message + contents, and the message envelope. The message contents include the + message header, and the message body. The message envelope is made up + of exactly one envelope sender address (which can be empty) and one or + more envelope recipient addresses. If the message cannot be delivered + for any reason, and the envelope sender address is not empty, the + message must be returned to the envelope sender address by the mail + transfer agent (MTA) which last accepted responsibility for delivering + the message. These notifications are known as "bounce messages" or + sometimes as "non-delivery notifications". Bounce messages are sent + using the empty envelope return path, to prevent mail loops from + occurring when a bounce message itself cannot be delivered. + + Confusion often arises among novice users about the difference between + the message header and the message envelope; they seem to believe that + they are not independant. This appears to be an artifact of their use + of simple-minded GUI mail user agents (MUAs) that do not allow them to + set the envelopes of their messages explicitly, but instead simply use + the contents of the From: header field as the envelope sender address, + and any addresses found in To:, cc:, and bcc: header fields as the + envelope recipient addresses. While these are sensible as default + values, more powerful MUAs allow the user to override this choice. + +Responsibility for recording the message envelope + + The last MTA to receive a message (usually the one running on the POP + or IMAP server where you retrieve your mail from) essentially acts as + your correspondence secretary, accepting your mail from the postman, + opening it, and placing it into your in-basket. Note that this would + normally destroy the important information contained in the message + envelope. To prevent this loss of information, this MTA is supposed to + copy the information from the envelope into new fields in the header of + the message content, as if your secretrary copied the sender and + recipient addresses onto the back of your letters in felt pen. + Unfortunately, some MTAs do not always do this properly, and envelope + information can then be lost. When this happens, it makes dealing with + certain types of mail messages problematic: + * bcc'd messages (bcc stands for blind carbon copy), where you are an + envelope recipient, but your address does not appear in the message + content (i.e., your address does not appear in a To:, cc:, or + similar message header field). With bcc'd messages, the From: + header field contains the name and address of the author of the + message, and the To: and cc: header fields contain the names and + addresses of the other, non-blind recipients of the message. + * mailing list messages, where you are an envelope recipient, but + your address does not appear in the message content (i.e., your + address does not appear in a To:, cc:, or similar message header + field). Mailing list messages have the envelope sender address set + to the mailing list manager (so that it can monitor "bad" list + addresses for bounces), while the From: header field contains the + name and address of the author of the message. The envelope + recipient addresses of mailing list messages are the addresses of + the list subscribers, while the To: header field usually contains + the address of the mailing list. + * other, less common cases. + + MTAs are supposed to record the envelope sender address by placing it + into a new Return-Path: header field at the top of the message. They + should then record the envelope recipient address(es) in another new + header field; sometimes this header field is named Delivered-To:, but + it can also be Envelope-To: or one of a few other names. + +How this relates to domain or multidrop mailboxes + + A domain or multidrop mailbox is one which receives mail for multiple + email addresses (commonly all addresses in a given domain). If you do + not want all of this mail to go to one person, you need to know who the + messages were originally addressed to after retrieving them from the + POP/IMAP multidrop mailbox. You cannot do this by looking at the To:, + cc:, or other informational message header fields, because they do not + actually reflect the message envelope at the time of delivery. Instead, + you have to reconstruct the envelope information from the message + header fields which the MTA on the server used to record it at the time + of delivery. + + If the final MTA does not record the message envelope (the envelope + sender, and all envelope recipient addresses in the domain mailbox the + message was sent to), then mail will be lost or misdirected regardless + of which software you use to access the mailbox. The mailbox cannot + actually be said to be a domain mailbox in this case; the defining + characteristic of a domain mailbox is that it records the envelope + correctly. The configuration of the MTA running on the server needs to + be fixed so that the envelope is properly recorded for every message it + receives. + +This rc stuff seems complicated. Does it have to be? + + The configuration file format is actually very simple; you don't need + to worry about most of it if you're not interested in using those + features. The simplest and most common getmail rc file configuration + will be for users who want to retrieve all mail from a single-user POP3 + mailbox, deliver those messages to a maildir or mbox file, and delete + the mail from the server. For maildir, that configuration is: +[options] +delete = True + +[retriever] +type = SimplePOP3Retriever +server = my-pop3-servername +username = my-pop3-username +password = my-pop3-password + +[destination] +type = Maildir +path = ~/Maildir/ + + For an mbox file, that configuration is: +[options] +delete = True + +[retriever] +type = SimplePOP3Retriever +server = my-pop3-servername +username = my-pop3-username +password = my-pop3-password + +[destination] +type = Mboxrd +path = ~/inbox + +How do I … + +How do I retrieve mail from multiple accounts? + + Create a separate getmail rc file for each account, and run getmail + with multiple --rcfile options. + + Of course, it's really easy to script this for a large number of rc-* + files. You might create a script in $HOME/bin/run-getmail.sh + containing: +#!/bin/sh +set -e +cd /path/to/my-rc-directory +rcfiles="" +for file in rc-* ; do + rcfiles="$rcfiles --rcfile $file" +done +exec /path/to/getmail $rcfiles $@ + + See any beginner's tutorial on Unix shell scripting for details. + +How do I get getmail to deliver messages to different mailboxes based on … + + If you want getmail to sort messages based on who they're from, or what + address appears in the To: or cc: header fields, or based on the + Subject: field contents, or anything like that, pick a filtering MDA + (like maildrop or procmail), and call it from a getmail MDA_external + destination. + +How do I stop getmail adding a Delivered-To: header to messages? + + Use the delivered_to [options] parameter. + +How do I stop getmail adding a Received: header to messages? + + Use the received [options] parameter. + +How do I make getmail deliver messages by re-injecting with SMTP? + + You don't need to. getmail can deliver to maildirs, mboxrd files, or + through arbitrary external MDAs. + + If you still think you need to, you can use getmail's external MDA + support to do so. + +How do I create a maildir? + + Use the maildirmake command, if you have it installed. Otherwise, run + the following command from your shell: +$ mkdir -p /path/to/Maildir/{cur,new,tmp} + + Some other maildir-aware programs ship with their own maildir-creation + programs; you can use those, or make the above shell command a + shellscript or alias if you like. + +How do I create an mboxrd file? + + Create a completely empty (i.e. zero bytes long) file via your + favourite method. The standard utility touch is commonly used: +$ touch /path/to/mboxrd + +How do I make getmail deliver messages to an mh folder? + + mh clients (and nmh, or "new mh" clients) include a command for + delivering a message into your mh folder. In nmh, this command is + called rcvstore. You use it as an external message delivery agent (MDA) + with getmail's MDA_external destination. Ensure your $HOME/.mh_profile + file is configured properly; getmail user Frankye Fattarelli suggests a + line like the following is necessary to indicate the path to your mh + mail root: +Path: Mail + + Then use MDA_external like this (which, after adjusting the path of the + command to reflect your mh/nmh installation, should work with either mh + or nmh): +[destination] +type = MDA_external +path = /usr/local/libexec/nmh/rcvstore +arguments = ("+inbox", ) + + Thanks to Frankye Fattarelli for contributing this answer. + +How do I run getmail in "daemon" mode? + + Use your system's cron utility to run getmail periodically if you wish + to have mail retrieved automatically at intervals. This is precisely + what cron is designed to do; there's no need to add special code to + getmail to do this. + + With a reasonably standard system cron utility, a crontab(5) entry like + the following will make getmail retrieve mail every hour: +0 * * * * /usr/local/bin/getmail --quiet + +How do I make getmail stop after retrieving X messages so that the server +actually flushes deleted messages? + + Use the max_messages_per_session option to limit the number of messages + getmail will process in a single session. Some users with flaky servers + use this option to reduce the chances of seeing messages more than once + if the server dies in mid-session. + +How do I make getmail retrieve mail from Hotmail? + + Well, you could write a retriever that speaks Hotmail's proprietary, + undocumented, and unsupported access protocol (or pay me to write one), + or simply set up the POP3 proxy from the httpmail package, and have + getmail retrieve mail from that POP3 proxy. + +I'm using getmail. How do I make it … + + These are supplementary questions I occasionally see about doing + various things to enhance a getmail setup. The solution to many of them + is to use a standard Unix technique of some sort to make the system + behave in a certain manner, or otherwise change the behaviour of + something that's actually outside of getmail proper. + +I'm running getmail from cron. How do I temporarily stop it? + + Some people ask about temporarily stopping getmail from running from a + cron job, possibly because the mail server is down and they don't want + to see the warnings cron mails them. + + The easiest method is to comment out getmail from your crontab file: + 1. Run +$ crontab -e + to edit your crontab file. + 2. Place a # (pound) character at the start of the line containing the + call to getmail. + 3. Save the changed file. + + When you want to re-enable getmail, edit the file again and un-do the + above change. + + If you need to do this on a regular basis, you can instead use a "flag + file" to tell the system whether or not to run getmail: + + Change your cron job or shellscript that normally launches getmail to + check for the presence of a certain file first, and have it not run + getmail if that file is present. For example, your crontab entry could + be changed to do this: + [ -f ~/.getmail/do-not-run ] || /path/to/getmail + + When you don't want getmail to run, touch that file: + $ touch ~/.getmail/do-not-run + + When you want getmail to run again, delete it: + $ rm -f ~/.getmail/do-not-run + + This is even safe for scripting, as creating and removing the file are + atomic operations under Unix. + +How do I stop multiple instances of getmail from running at the same time? + + getmail has no problems running multiple instances in parallel, though + you shouldn't attempt to use the same getmail rc file from two + different instances at the same time. If you need to prevent two + instances of getmail from running simultaneously, use any standard Unix + method of providing a mutex for this purpose. One example would be to + run getmail under a program like setlock (part of the daemontools + package). Change your script or crontab file to invoke getmail like + this: +/path/to/setlock -n /path/to/lockfile /path/to/getmail [getmail options] + + There are other programs that provide functionality similar to setlock. + +Using getmail with other software + + getmail user Frankye Fattarelli contributed to the following questions + about integrating getmail with SpamAssassin and ClamAV. + +How do I use SpamAssassin with getmail? + + SpamAssassin can be run in standalone mode or in a client/server + configuration. In both configurations, SpamAssassin accepts a wide + variety of arguments; please refer to SpamAssassin's manual pages or + online documentation for details. + + To filter messages through SpamAssassin in a client/server + configuration (i.e. with the spamd daemon), use a configuration like + this: +[filter] +type = Filter_external +path = /usr/local/bin/spamc +arguments = ("-s 10000", ) + + The value supplied to the -s option is the maximum message size + accepted (in bytes). The default is 250k. + + A similar configuration without the spamd daemon would be: +[filter] +type = Filter_external +path = /usr/local/bin/spamassassin +arguments = ("--report", ) + + The --report option sends the message to the various spam-blocker + databases and tags it as spam in your bayesian database. + + Note that if you are using Bayesian (learning) filtering, and you've + put your SpamAssassin filter after any getmail Filter_classifier, you + may have a problem with your learning filter learning getmail's header + fields. That is, the headers added by the other filters may get + learned, and affect your database. To prevent this, ensure that + SpamAssassin ignores these fields by adding the following to your + SpamAssassin configuration: +bayes_ignore_header X-getmail-filter-classifier + +How do I use ClamAV with getmail? + + You should also read this message in the getmail users' mailing list + archives and the ClamAV documentation if you want to use ClamAV with + getmail. + + ClamAV, like SpamAssassin, can by used in standalone or client/server + configurations. In either case, you need to add the StreamSaveToDisk + option to your clamav.conf file to enable scanning from stdin. + + To use ClamAV without the clamd daemon, use a filter configuration like + this: +[filter] +type = Filter_classifier +path = /usr/local/bin/clamscan +arguments = ("--stdout", "--no-summary", + "--mbox", "--infected", "-") +exitcodes_drop = (1,) + + The above assumes you do not want the infected emails to be delivered. + If you do want them delivered, you would use a slightly different + configuration: +[filter] +type = Filter_classifier +path = /usr/local/bin/clamscan +arguments = ("--stdout", "--no-summary", + "--mbox", "--infected", "-") +exitcodes_keep = (0,1) + + To use ClamAV with the clamd daemon, use a filter configuration like + this: +[filter] +type = Filter_classifier +path = /usr/local/bin/clamdscan +arguments = ("--stdout", "--disable-summary", "-") +exitcodes_drop = (1, ) + + As with Clamscan (above), if you do want the infected messages + delivered instead of dropped, you should modify your configuration as + follows: +[filter] +type = Filter_classifier +path = /usr/local/bin/clamdscan +arguments = ("--stdout", "--disable-summary", "-") +exitcodes_keep = (0,1) + + You may find it necessary to specify the paths of some decompression + utilities used by ClamAV with additional arguments like: +arguments = ( …, + "--unzip=/usr/local/bin/unzip", + "--unrar=/usr/local/bin/unrar", + "--unarj=/usr/local/bin/unarj", + "--lha=/usr/local/bin/lha", + "--jar=/usr/local/bin/unzip", + "--tar=/usr/bin/tar", + "--tgz=/usr/bin/tar" + + Note: if you want to use the daemonized (client/server) version of + ClamAV, ensure that your clamav.conf file contains: +ScanMail + + The paths to the various decompression utilities must be specified in + this file as well. + + See the following mailing list message from Frankye Fattarelli for + additional notes on using ClamAV with getmail: + http://marc.theaimsgroup.com/?l=getmail&m=109128345509273&w=2 + +Getting prettier output from ClamAV + + Using getmail's Filter_classifier, the output of your filtering program + (in this case ClamAV) is placed into a X-getmail-filter-classifier: + header field in the message. This can make auditing the actions of + filters difficult if you use multiple filters and cannot tell which + filter added which line. + + To correct this, you can use an additional filter to change the name of + the added filter header lines immediately after each filter is run. For + example, reformail, from the maildrop package (which is in turn part of + the Courier MTA ) can be used in this fashion to rename the added + header fields (say, to "X-mypersonalmailscan") with a filter + configuration like this: +type = Filter_external +path = /usr/local/bin/reformail +arguments = ("-R", "X-getmail-filter-classifier:", + "X-mypersonalmailscan:") + + Simply ensure ClamAV is invoked as the first filter, and this is + invoked as the second filter (or immediately after the ClamAV filter, + if it is the second, third, etc. filter). + +How do I use F-Prot with getmail? + + getmail user Kai Raven reports that getmail and F-Prot work fine + together with the following getmailrc filter configuration: +[filter] +type = Filter_external +path = /usr/local/bin/f-prot-wrapper.sh + + The wrapper script f-prot-wrapper.sh is a small shellscript by Ali Onur + Cinar, and can be downloaded from his website. + +How do I use procmail with getmail? + + Simply invoke procmail as an external MDA. procmail requires that one + of the following be true: + * that the message begin with a Unix "From " line (the mbox message + delimiter) + * that procmail is invoked with the -f option supplying the envelope + sender, so that it may generate the "From " line + + To have getmail generate and prepend the "From " line to the start of + the message, set the MDA_external parameter unixfrom to True: +[destination] +type = MDA_external +path = /path/to/procmail +unixfrom = True + + To supply the -f option to procmail, do something like this: +[destination] +type = MDA_external +path = /path/to/procmail +arguments = ("-f", "%(sender)") + +How do I use maildrop with getmail? + + Simply invoke maildrop as an external MDA. maildrop requires that the + message begin with a Unix "From " line (the mbox message delimiter), so + you'll need to either set the MDA_external parameter unixfrom to True, + or supply arguments that tell maildrop to recreate this line. One of + the following would be fine: +[destination] +type = MDA_external +path = /path/to/maildrop +arguments = ("-f", "%(sender)") + + Or: +[destination] +type = MDA_external +path = /path/to/maildrop +unixfrom = True + + If you want to specify a maildrop rc file as one of its arguments, that + would be something like: +[destination] +type = MDA_external +path = /path/to/maildrop +arguments = ("-f", "%(sender)", "~/.maildroprc") + +How do I use TMDA with getmail? + + Simply use the Filter_TMDA module as a message filter: +[filter-X] +type = Filter_TMDA + + See the documentation for details on optional parameters to the + Filter_TMDA module. + +How can I get Gmail labels with getmail? + + As of getmail version 4.34.0, getmail retrieves the labels and other + metadata that Gmail makes available via an IMAP extension, and records + that information in the message headers X-GMAIL-LABELS:, + X-GMAIL-THRID:, and X-GMAIL-MSGID:. + +I think I found this bug in getmail … + + I get frequent reports like the following, which aren't bugs in + getmail. Please read them before reporting them to me. + +getmail doesn't download all my mail from Gmail … + + There's a couple of different problems here. One is that Google's Gmail + service violates the POP3 protocol by removing messages from the POP3 + view of the mailbox without the user issuing a DELE command. They do + this as soon as an RETR command is given, so if getmail tries to + download a message and it fails for any reason (delivery fails due to a + full disk, or the Gmail server fails to respond, or the network + connection dies before the transfer is complete, or the Gmail server + fails to respond to the QUIT command, or …), the next time getmail + connects to that Gmail account, Gmail will have "helpfully" deleted the + message from the POP3 mailbox, even though getmail never issued a DELE + command. So Gmail silently destroys mail, from a POP3 perspective. + There's nothing getmail can do about this. + + Note this feature of Gmail is not well-publicized. The only mention I + can find of it is here: + http://mail.google.com/support/bin/answer.py?answer=13291&topic=1555 + + The other issue here is that Google doesn't include mail from your + trash or spam folders in the POP3 view, so getmail can't see those + messages either. That's generally less of an issue, provided their spam + filters never give false positive results (ha!). + +FutureWarning: %u/%o/%x/%X of negative int will return a signed string in +Python 2.4 and up + + Various people have reported this "bug" in getmail, where they see the + following warning when getmail is run: +/usr/lib/python2.3/optparse.py:668: FutureWarning: %u/%o/%x/%X of negative int w +ill return a signed string in Python 2.4 and up + return ("<%s at 0x%x: %r>" + + This warning is a bug in Python 2.3.4's optparse.py module, not in + getmail. Feel free to report it to the Python team if the most recent + release of Python hasn't fixed it. I reported it in June, 2004. + +AttributeError: 'module' object has no attribute 'fsync' + + Various people have reported this "bug" in getmail — it's actually a + bug in some versions of Python 2.3.X. It was fixed in Python version + 2.3.3. getmail 4 detects problematic versions of Python and refuses to + run, but you can still encounter this problem with getmail version 3 if + you try to run it with a broken Python version. + +operation error (SimplePOP3Retriever: [...] does not uniquely identify +messages [...] see documentation or use BrokenUIDLPOP3Retriever instead + + The server you're trying to use does not properly uniquely identify + messages (getmail noticed when it saw the same "unique" identifier + twice in the same mailbox at the same time). getmail needs these + identifiers to be unique so that it can properly tell the difference + between new and old messages. + + If you see this error message, and you've configured getmail to + retrieve and immediately delete all messages, just switch to using the + BrokenUIDLPOP3Retriever class (or its SSL variant) -- it'll work fine. + + If you see this error message, and you're trying to leave messages on + the server after retrieval (permanently, or for a few days with + delete_after), you have a few options to try to resolve it: + * If your provider also offers IMAP access to your mailbox, try one + of the IMAP retrievers instead. + * Change your configuration so you're not leaving messages on the + server, and use BrokenUIDLPOP3Retriever instead. + * Talk to your mail hosting provider, and see if they can fix their + POP3 software so that it doesn't have this problem any more. + +MemoryError on OS X + + If you see errors like this while running getmail on Macintosh OS X: +python2.5(27172) malloc: *** vm_allocate(size=15699968) failed (error code=3) +python2.5(27172) malloc: *** error: can't allocate region +python2.5(27172) malloc: *** set a breakpoint in szone_error to debug +[...] + + ... which then end with MemoryError, please report the problem to + Apple. The OS X implementation of realloc() is broken, and there's + nothing getmail can do about it. + +MemoryError when using IMAP + + If you see errors like this while running getmail configured to + retrieve mail via IMAP or IMAP-over-SSL: +Python(24006) malloc: *** mmap(size=9875456) failed (error code=12) +[...] + + ... which then end with MemoryError, you've run into a bug in Python's + IMAP library. It's fixed in the most recent versions of Python 2.5 and + 2.6. This bug can cause getmail to grow to a huge size, vastly out of + proportion to the size of the message it's retrieving, at which point + Python may fail or be killed when the system runs out of memory. + + Upgrade your Python installation to the newest Python 2.5 or 2.6 + version to fix the problem, or use POP3 instead of IMAP to work around + it.

@@ -0,0 +1,270 @@ + Link: Contents Up Index: Charles Cazabon's Software + + getmail documentation + + This is the documentation for getmail version 4. Version 4 includes + numerous changes from version 3.x; if you are using getmail version 3, + please refer to the documentation included with that version of the + software. + + getmail is Copyright (c) 1998-2009 Charles Cazabon. + + getmail is licensed under the GNU General Public License version 2 (only). + If you wish to obtain a license to distribute getmail under other terms, + please contact me directly. + + Troubleshooting problems + + This section of the documentation is to be added to as getmail version 4 + progresses through beta testing to release state. If you have suggestions + for additions or changes to this documentation, please send them to the + mailing list or me. + +Error messages + + getmail may output various diagnostic error messages. The common ones and + their meanings are given below. + + ImportError: getmail version 4 requires Python version 2.3.3 or later + + You tried to run getmail 4 with a version of Python prior to Python 2.3.3. + This is unsupported. If you cannot install a newer Python alongside your + current version, please use getmail version 3, which supports Python 1.5.2 + and later. + + Configuration error: ... + + getmail detected an error in your configuration. Check your getmail rc + file(s). getmail will do its best to point out the exact cause of the + error. Some of the specific errors it may find include the following. + + Configuration error: missing required configuration parameter name + + A class object in your getmail rc file requires the parameter name, but it + was not found in the appropriate section of the file. + + Configuration error: configuration value name (value) not of required type + type (why) + + The configuration parameter name must be of type type, but the supplied + value value does not appear to be of that type. Further information may be + present in why. + + The getmail documentation contains descriptions of the syntax for each + parameter type. + + Configuration error: maildir path missing trailing / + + Maildir paths must start with dot or slash and end with a slash. + + Configuration error: not a maildir (path) + + The specified maildir path path does not appear to be a valid maildir. + Check to ensure that it is a valid maildir, and that getmail has + permission to write to it. + + Configuration error: ... (path: maildir subdirectory "path" does not exist) + + The specified maildir path path does not appear to be a valid maildir, as + it is missing one of the required subdirectories. Check to ensure that it + is a valid maildir and that getmail has permission to write to it. + + Configuration error: not an mboxrd file (path) + + The specified mboxrd path path does not appear to be a valid mboxrd file. + To avoid corrupting files in the event of a user typo, getmail will not + deliver messages to files that do not appear to be valid mboxrd files. + + Configuration error: mboxrd does not exist + + The specified mboxrd does not exist. getmail will not create mbox files; + ensure they exist before trying to deliver to them. + + Configuration error: the fieldname header field does not record the envelope + recipient address + + In a multidrop retriever configuration, you specified that the envelope + recipient was recorded in a header field that getmail knows does not + actually record that information. + + Configuration error: refuse to invoke external commands as root or GID 0 by + default + + By default, getmail will not invoke external commands (in destinations or + filters) when it is running with root privileges, for security reasons. + See the documenation for possible solutions. + + Configuration error: no such command path + + An external command was specified as being located at path path, but the + command executable was not found at that location. + + Configuration error: path not executable + + A specified external command at path path was found to not be an + executable file. + + Configuration error: destination specifies section name section which does + not exist + + A destination in the getmail rc file refers to another rc file section + named section, but that section was not found in the file. + + Retrieval error ... + + getmail detected an error while trying to retrieve a message. Some of the + specific errors it may find include the following. + + Retrieval error: server ... is broken; ... + + The server claimed to have a particular message, but when getmail tried to + retrieve it, the server returned an empty response in violation of the POP + or IMAP protocol. getmail will skip on to the next message. + + This problem is almost always with an MSExchange server, and is due to + bugs in MSExchange. Delete the offending message from the mailbox via the + webmail interface if you don't want to see this error message, and report + the bug to the server administrator or Microsoft. + + Delivery error ... + + getmail detected an error after retrieving a message but before delivery + was successfully completed. Some of the specific errors it may find + include the following. + + Delivery error: maildir delivery process failed (refuse to deliver mail as + root) + + getmail will not deliver to a maildir as the root user. You may specify an + alternate user to deliver as with the user directive in the destination + section of your getmailrc file, or let getmail default to the user who is + the owner of the maildir. + + Delivery error: mbox delivery process failed (refuse to deliver mail as + root) + + getmail will not deliver to an mbox file as the root user. You may specify + an alternate user to deliver as with the user directive in the destination + section of your getmailrc file, or let getmail default to the user who is + the owner of the mbox file. + + Delivery error: mbox delivery process failed (not an mboxrd file) + + The specified mbox file does not appear to be a valid mbox file. + + Error: ... + + getmail detected an operational error. getmail will do its best to point + out the exact cause of the error. Common causes are failures to connect to + a remote mail server, timeouts during network operations, and other + transient failures. + + Error: server-info does not uniquely identify messages ... + + The POP3 server for this particular account was not able to uniquely + identify the messages in the mailstore. You can use the + BrokenUIDLPOP3Retriever class with this server instead, but functionality + is limited because of the inability to identify messages properly. + + Error: server-info failed to identify message X in UIDL output ... + + The POP3 server for this particular account completely failed to identify + one of the messages in the mailstore when the UIDL command was issued. The + POP server is in violation of the POP3 protocol, and getmail has no way to + identify the message in question. + + The most common cause of this is servers that use the contents of the + Message-ID: header field as the UIDL value for the message - some messages + (usually spam) lack a Message-ID: header field entirely, causing these + servers to emit blank UIDL values for these messages, which is not + permitted by the POP3 protocol. You may be able to work around the problem + by deleting the problematic message(s) from the mailstore by other means + (such as a webmail interface provided by your POP3 mailhost). + + Otherwise, you'll need to either ask the postmaster of the POP3 mail host + to fix the POP3 software they're using. In the meantime, you can use the + BrokenUIDLPOP3Retriever class with this server instead, but functionality + is limited because of the inability to identify messages properly. + + Python(...) malloc: *** mmap(...) failed (...) + + ... followed by an Unhandled exception block and then MemoryError. + + getmail ran out of memory, usually due to a bug in Python's IMAP library + which was fixed in early 2008. + + If you are using IMAP and run into this problem retrieving messages that + aren't hundreds of megabytes in size, you can almost certainly fix it by + upgrading your Python installation to the latest 2.5.x or 2.6.x release. + Note that if you switch from Python 2.5.x to Python 2.6.x, you'll need to + re-install getmail with python setup.py install from the getmail source + directory. + +Warning messages + + getmail may output various diagnostic warning messages. The common ones + and their meanings are given below. + + Warning: ... + + getmail detected a condition which might be problematic. Some of the + specific warnings it may find include the following. + + Warning: ignoring unknown parameter "parameter_name" + + A getmail rc file contained an unknown parameter. This usually indicates + that you've put the parameter in the wrong section of the file (such as + putting the read_all parameter in the [retriever] section instead of in + the [options] section). + + Warning: filter filter returned fewer headers (X) than supplied (Y) + + A message filter appeared to incorrectly remove header fields from the + header of a message which it handled. getmail warns you about this so that + you can check your filter for proper operation. Filters should add + information to the message header or leave it alone; check the + configuration for the filter program you are using. + +Unexpected Behaviour + + If getmail is behaving in a manner other that you expected, see the + following sections. + + getmail uses the wrong hostname for my machine + + If getmail records a hostname other than the "right" one for your host (in + its Received: trace header fields), check your /etc/hosts file and make + sure the "right" name is the first hostname listed for any of the + addresses of the machine. + + getmail puts "unknown" in the Delivered-To: or Return-Path:header field + + getmail records the envelope recipient address in the Delivered-To: header + field, and the envelope sender in the Return-Path: header field. If this + information is not available (because you're not using a multidrop + retriever class, or the MTA on the POP/IMAP server is broken, for + example), getmail uses the string "unknown". You can disable the creation + of the Delivered-To: header field if you wish. + + getmail isn't replacing my command argument "%(recipient)" with the message + recipient address + + The %(recipient), %(local), and %(domain) replacement strings are only + replaced if the message is retrieved with a multidrop retriever class; + otherwise, getmail does not "know" the recipient address of the message, + and therefore cannot perform this replacement. + + getmail seems to take longer than expected to initialize + + If getmail takes more than a few seconds to initialize, run the following + command to test: + + python -c "import socket; print socket.getfqdn()" + + If this seems to take a similarly long period of time to complete, the + delay is in finding the fully-qualified hostname of your system. The fix + is to ensure you have a valid mapping of address-to-hostname for all the + addresses in your system. You can do this in your /etc/hosts file, in your + authoritative content DNS server, or in another system-specific manner - + please contact your OS vendor (or its public support mailing list) for + assistance.

@@ -34,6 +34,7 @@ 'received', 'message_log_verbose', 'message_log_syslog', + 'fingerprint', ) options_int = ( 'delete_after', @@ -85,6 +86,7 @@ 'message_log_verbose' : False, 'message_log_syslog' : False, 'logfile' : None, + 'fingerprint' : False, } @@ -393,11 +395,13 @@ log.debug('retriever %s finished\n' % retriever) try: if idle and not retriever.supports_idle: - log.info('--idle given, but chosen retriever does not support' - 'IDLE\n') + log.info('--idle given, but retriever does not support IDLE\n') + idle = False + if idle and sys.version_info < (2, 5, 0): + log.info('--idle requires Python 2.5 or higher\n') idle = False - if not errorexit and idle: + if idle and not errorexit: # TODO # Okay, so what should really happen here is that when go_idle # returns, getmail should use the *existing* connection to check @@ -414,8 +418,12 @@ # value of idling, a failed connection will cause it to become # False, which will make the main go() loop reconnect, which is # what we want. + # Expunge and close the mailbox to prevent the same messages + # being pulled again in some configurations. + retriever.close_mailbox() try: idling = retriever.go_idle(idle) + # Returned from idle configs.append(configs[0]) continue except KeyboardInterrupt, o: @@ -493,6 +501,11 @@ help='operate more verbosely (may be given multiple times)' ) overrides.add_option( + '--fingerprint', + dest='override_fingerprint', action='store_true', + help='show SSL/TLS fingerprint and connection information' + ) + overrides.add_option( '-q', '--quiet', dest='override_verbose', action='store_const', const=0, @@ -591,6 +604,7 @@ 'message_log' : defaults['message_log'], 'message_log_verbose' : defaults['message_log_verbose'], 'message_log_syslog' : defaults['message_log_syslog'], + 'fingerprint' : defaults['fingerprint'], } # Python's ConfigParser .getboolean() couldn't handle booleans in # the defaults. Submitted a patch; they fixed it a different way. @@ -805,7 +819,7 @@ ) # Apply overrides from commandline - for option in ('read_all', 'delete', 'verbose'): + for option in ('read_all', 'delete', 'verbose', 'fingerprint'): val = getattr(options, 'override_%s' % option) if val is not None: log.debug('overriding option %s from commandline %s\n'

@@ -2,7 +2,7 @@ Summary: POP3 mail retriever with reliable Maildir delivery Name: getmail -Version: 4.43.0 +Version: 4.46.0 Release: 1 License: GPL Group: Applications/Internet @@ -52,6 +52,33 @@ %{python_sitelib}/getmailcore/ %changelog +* Sun Apr 06 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.46.0 + +* Sun Apr 06 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.46.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.45.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.45.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + +* Sat Mar 22 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + +* Sat Mar 22 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + * Sun Aug 25 2013 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> -update to version 4.43.0

@@ -16,7 +16,7 @@ raise ImportError('getmail version 4 requires Python version 2.3.3' ' or later') -__version__ = '4.43.0' +__version__ = '4.46.0' __all__ = [ 'baseclasses',

@@ -53,6 +53,124 @@ except ImportError: pass +# hashlib only present in python2.5, ssl in python2.6; used together +# in SSL functionality below +try: + import ssl +except ImportError: + ssl = None +try: + import hashlib +except ImportError: + hashlib = None + +# If we have an ssl module: +if ssl: + # Is it recent enough to have hostname matching (Python 3.2+)? + try: + ssl_match_hostname = ssl.match_hostname + except AttributeError: + # Running a Python with no hostname matching + def _dnsname_match(dn, hostname, max_wildcards=1): + """Matching according to RFC 6125, section 6.4.3 + http://tools.ietf.org/html/rfc6125#section-6.4.3 + """ + pats = [] + if not dn: + return False + + parts = dn.split(r'.') + leftmost = parts[0] + remainder = parts[1:] + + wildcards = leftmost.count('*') + if wildcards > max_wildcards: + # Issue #17980: avoid denials of service by refusing more + # than one wildcard per fragment. A survery of established + # policy among SSL implementations showed it to be a + # reasonable choice. + raise getmailOperationError( + "too many wildcards in certificate DNS name: " + repr(dn)) + + # speed up common case w/o wildcards + if not wildcards: + return dn.lower() == hostname.lower() + + # RFC 6125, section 6.4.3, subitem 1. + # The client SHOULD NOT attempt to match a presented identifier + # in which the wildcard character comprises a label other than + # the left-most label. + if leftmost == '*': + # When '*' is a fragment by itself, it matches a non-empty + # dotless fragment. + pats.append('[^.]+') + elif leftmost.startswith('xn--') or hostname.startswith('xn--'): + # RFC 6125, section 6.4.3, subitem 3. + # The client SHOULD NOT attempt to match a presented identifier + # where the wildcard character is embedded within an A-label or + # U-label of an internationalized domain name. + pats.append(re.escape(leftmost)) + else: + # Otherwise, '*' matches any dotless string, e.g. www* + pats.append(re.escape(leftmost).replace(r'\*', '[^.]*')) + + # add the remaining fragments, ignore any wildcards + for frag in remainder: + pats.append(re.escape(frag)) + + pat = re.compile(r'\A' + r'\.'.join(pats) + r'\Z', re.IGNORECASE) + return pat.match(hostname) + + + def ssl_match_hostname(cert, hostname): + """Verify that *cert* (in decoded format as returned by + SSLSocket.getpeercert()) matches the *hostname*. RFC 2818 and + RFC 6125 rules are followed, but IP addresses are not accepted + for *hostname*. + + getmailOperationError is raised on failure. On success, the function + returns nothing. + """ + if not cert: + raise ValueError("empty or no certificate, ssl_match_hostname " + "needs an SSL socket or SSL context with " + "either CERT_OPTIONAL or CERT_REQUIRED") + dnsnames = [] + san = cert.get('subjectAltName', ()) + for key, value in san: + if key == 'DNS': + if _dnsname_match(value, hostname): + return + dnsnames.append(value) + if not dnsnames: + # The subject is only checked when there is no dNSName entry + # in subjectAltName + for sub in cert.get('subject', ()): + for key, value in sub: + # XXX according to RFC 2818, the most specific + # Common Name must be used. + if key == 'commonName': + if _dnsname_match(value, hostname): + return + dnsnames.append(value) + if len(dnsnames) > 1: + raise getmailOperationError("hostname %s " + "doesn't match either of %s" + % (hostname, ', '.join(map(repr, dnsnames)))) + elif len(dnsnames) == 1: + raise getmailOperationError("hostname %s " + "doesn't match %s" + % (hostname, dnsnames[0])) + else: + raise getmailOperationError("no appropriate commonName or " + "subjectAltName fields were found") + +try: + from email.header import decode_header +except ImportError, o: + # python < 2.5 + from email.Header import decode_header + from getmailcore.compatibility import * from getmailcore.exceptions import * from getmailcore.constants import * @@ -112,6 +230,9 @@ EAI_FAIL = getattr(socket, 'EAI_FAIL', NO_OBJ) +# Constant for POPSSL +POP3_SSL_PORT = 995 + # # Mix-in classes # @@ -142,6 +263,55 @@ ####################################### +class POP3_SSL_EXTENDED(poplib.POP3_SSL): + # Extended SSL support for POP3 (certificate checking, + # fingerprint matching, cipher selection, etc.) + + def __init__(self, host, port=POP3_SSL_PORT, keyfile=None, + certfile=None, ssl_version=None, ca_certs=None, + ssl_ciphers=None): + self.host = host + self.port = port + self.keyfile = keyfile + self.certfile = certfile + self.ssl_version = ssl_version + self.ca_certs = ca_certs + self.ssl_ciphers = ssl_ciphers + + self.buffer = '' + msg = "getaddrinfo returns an empty list" + self.sock = None + for res in socket.getaddrinfo(self.host, self.port, 0, + socket.SOCK_STREAM): + (af, socktype, proto, canonname, sa) = res + try: + self.sock = socket.socket(af, socktype, proto) + self.sock.connect(sa) + except socket.error, msg: + if self.sock: + self.sock.close() + self.sock = None + continue + break + if not self.sock: + raise socket.error(msg) + extra_args = {} + if self.ssl_version: + extra_args['ssl_version'] = self.ssl_version + if self.ca_certs: + extra_args['cert_reqs'] = ssl.CERT_REQUIRED + extra_args['ca_certs'] = self.ca_certs + if self.ssl_ciphers: + extra_args['ciphers'] = self.ssl_ciphers + + self.file = self.sock.makefile('rb') + self.sslobj = ssl.wrap_socket(self.sock, self.keyfile, + self.certfile, **extra_args) + self._debugging = 0 + self.welcome = self._getresp() + + +####################################### class Py24POP3SSLinitMixIn(object): '''Mix-In class to do POP3 over SSL initialization with Python 2.4's poplib.POP3_SSL class. @@ -154,8 +324,39 @@ 'SSL not supported by this installation of Python' ) (keyfile, certfile) = check_ssl_key_and_cert(self.conf) - try: - if keyfile: + ca_certs = check_ca_certs(self.conf) + ssl_version = check_ssl_version(self.conf) + ssl_fingerprints = check_ssl_fingerprints(self.conf) + ssl_ciphers = check_ssl_ciphers(self.conf) + using_extended_certs_interface = False + try: + if ca_certs or ssl_version or ssl_ciphers: + using_extended_certs_interface = True + # Python 2.6 or higher required, use above class instead of + # vanilla stdlib one + msg = '' + if keyfile: + msg += 'with keyfile %s, certfile %s' % (keyfile, certfile) + if ssl_version: + if msg: + msg += ', ' + msg += ('using protocol version %s' + % self.conf['ssl_version'].upper()) + if ca_certs: + if msg: + msg += ', ' + msg += 'with ca_certs %s' % ca_certs + + self.log.trace( + 'establishing POP3 SSL connection to %s:%d %s' + % (self.conf['server'], self.conf['port'], msg) + + os.linesep + ) + self.conn = POP3_SSL_EXTENDED( + self.conf['server'], self.conf['port'], keyfile, certfile, + ssl_version, ca_certs, ssl_ciphers + ) + elif keyfile: self.log.trace( 'establishing POP3 SSL connection to %s:%d with ' 'keyfile %s, certfile %s' @@ -173,6 +374,41 @@ self.conn = poplib.POP3_SSL(self.conf['server'], self.conf['port']) self.setup_received(self.conn.sock) + if ssl and hashlib: + sslobj = self.conn.sslobj + peercert = sslobj.getpeercert(True) + ssl_cipher = sslobj.cipher() + if ssl_cipher: + ssl_cipher = '%s:%s:%s' % ssl_cipher + if not peercert: + actual_hash = None + else: + actual_hash = hashlib.sha256(peercert).hexdigest().lower() + else: + actual_hash = None + ssl_cipher = None + + # Ensure cert is for server we're connecting to + if ssl and self.conf['ca_certs']: + ssl_match_hostname(self.conn.sslobj.getpeercert(), + self.conf['server']) + + if ssl_fingerprints: + if not actual_hash: + raise getmailOperationError( + 'socket ssl_fingerprints mismatch (no cert provided)' + ) + + any_matches = False + for expected_hash in ssl_fingerprints: + if expected_hash == actual_hash: + any_matches = True + if not any_matches: + raise getmailOperationError( + 'socket ssl_fingerprints mismatch (got %s)' + % actual_hash + ) + except poplib.error_proto, o: raise getmailOperationError('POP error (%s)' % o) except socket.timeout: @@ -202,6 +438,15 @@ 'SSL not supported by this installation of Python' ) (keyfile, certfile) = check_ssl_key_and_cert(self.conf) + ca_certs = check_ca_certs(self.conf) + ssl_version = check_ssl_version(self.conf) + ssl_fingerprints = check_ssl_fingerprints(self.conf) + ssl_ciphers = check_ssl_ciphers(self.conf) + if ca_certs or ssl_version or ssl_ciphers or ssl_fingerprints: + raise getmailConfigurationError( + 'SSL extended options are not supported by this' + ' installation of Python' + ) try: if keyfile: self.log.trace( @@ -220,6 +465,7 @@ + os.linesep ) self.conn = POP3SSL(self.conf['server'], self.conf['port']) + self.setup_received(self.conn.rawsock) except poplib.error_proto, o: raise getmailOperationError('POP error (%s)' % o) @@ -259,6 +505,35 @@ + os.linesep) +####################################### +class IMAP4_SSL_EXTENDED(imaplib.IMAP4_SSL): + # Similar to above, but with extended support for SSL certificate checking, + # fingerprints, etc. + def __init__(self, host='', port=imaplib.IMAP4_SSL_PORT, keyfile=None, + certfile=None, ssl_version=None, ca_certs=None, + ssl_ciphers=None): + self.ssl_version = ssl_version + self.ca_certs = ca_certs + self.ssl_ciphers = ssl_ciphers + imaplib.IMAP4_SSL.__init__(self, host, port, keyfile, certfile) + + def open(self, host='', port=imaplib.IMAP4_SSL_PORT): + self.host = host + self.port = port + self.sock = socket.create_connection((host, port)) + extra_args = {} + if self.ssl_version: + extra_args['ssl_version'] = self.ssl_version + if self.ca_certs: + extra_args['cert_reqs'] = ssl.CERT_REQUIRED + extra_args['ca_certs'] = self.ca_certs + if self.ssl_ciphers: + extra_args['ciphers'] = self.ssl_ciphers + + self.sslobj = ssl.wrap_socket(self.sock, self.keyfile, self.certfile, + **extra_args) + self.file = self.sslobj.makefile('rb') + ####################################### class IMAPSSLinitMixIn(object): @@ -272,8 +547,39 @@ 'SSL not supported by this installation of Python' ) (keyfile, certfile) = check_ssl_key_and_cert(self.conf) - try: - if keyfile: + ca_certs = check_ca_certs(self.conf) + ssl_version = check_ssl_version(self.conf) + ssl_fingerprints = check_ssl_fingerprints(self.conf) + ssl_ciphers = check_ssl_ciphers(self.conf) + using_extended_certs_interface = False + try: + if ca_certs or ssl_version or ssl_ciphers: + using_extended_certs_interface = True + # Python 2.6 or higher required, use above class instead of + # vanilla stdlib one + msg = '' + if keyfile: + msg += 'with keyfile %s, certfile %s' % (keyfile, certfile) + if ssl_version: + if msg: + msg += ', ' + msg += ('using protocol version %s' + % self.conf['ssl_version'].upper()) + if ca_certs: + if msg: + msg += ', ' + msg += 'with ca_certs %s' % ca_certs + + self.log.trace( + 'establishing IMAP SSL connection to %s:%d %s' + % (self.conf['server'], self.conf['port'], msg) + + os.linesep + ) + self.conn = IMAP4_SSL_EXTENDED( + self.conf['server'], self.conf['port'], keyfile, certfile, + ssl_version, ca_certs, ssl_ciphers + ) + elif keyfile: self.log.trace( 'establishing IMAP SSL connection to %s:%d with keyfile ' '%s, certfile %s' @@ -292,6 +598,41 @@ self.conn = imaplib.IMAP4_SSL(self.conf['server'], self.conf['port']) self.setup_received(self.conn.sock) + if ssl and hashlib: + sslobj = self.conn.ssl() + peercert = sslobj.getpeercert(True) + ssl_cipher = sslobj.cipher() + if ssl_cipher: + ssl_cipher = '%s:%s:%s' % ssl_cipher + if not peercert: + actual_hash = None + else: + actual_hash = hashlib.sha256(peercert).hexdigest().lower() + else: + actual_hash = None + ssl_cipher = None + + # Ensure cert is for server we're connecting to + if ssl and self.conf['ca_certs']: + ssl_match_hostname(self.conn.ssl().getpeercert(), + self.conf['server']) + + if ssl_fingerprints: + if not actual_hash: + raise getmailOperationError( + 'socket ssl_fingerprints mismatch (no cert provided)' + ) + + any_matches = False + for expected_hash in ssl_fingerprints: + if expected_hash == actual_hash: + any_matches = True + if not any_matches: + raise getmailOperationError( + 'socket ssl_fingerprints mismatch (got %s)' + % actual_hash + ) + except imaplib.IMAP4.error, o: raise getmailOperationError('IMAP error (%s)' % o) except socket.timeout: @@ -311,14 +652,25 @@ % (self.conf['server'], o) ) else: - raise getmailOperationError('socket error during connect (%s)' % o) + raise getmailOperationError('socket error during connect (%s)' + % o) except socket.sslerror, o: raise getmailOperationError( 'socket sslerror during connect (%s)' % o ) - self.log.trace('IMAP SSL connection %s established' % self.conn - + os.linesep) + fingerprint_message = ('IMAP SSL connection %s established' + % self.conn) + if actual_hash: + fingerprint_message += ' with fingerprint %s' % actual_hash + if ssl_cipher: + fingerprint_message += ' using cipher %s' % ssl_cipher + fingerprint_message += os.linesep + + if self.app_options['fingerprint']: + self.log.info(fingerprint_message) + else: + self.log.trace(fingerprint_message) # # Base classes @@ -1006,18 +1358,33 @@ % g['mailbox']) return mailboxes + def close_mailbox(self): + # Close current mailbox so deleted mail is expunged. One getmail + # user had a buggy IMAP server that didn't do the automatic expunge, + # so we do it explicitly here. + self.conn.expunge() + self.conn.close() + self.write_oldmailfile(self.mailbox_selected) + # And clear some state + self.mailbox_selected = False + self.mailbox = None + self.uidvalidity = None + self.msgnum_by_msgid = {} + self.msgid_by_msgnum = {} + self.sorted_msgnum_msgid = () + self._mboxuids = {} + self._mboxuidorder = [] + self.msgsizes = {} + self.oldmail = {} + self.__delivered = {} + def select_mailbox(self, mailbox): self.log.trace() assert mailbox in self.mailboxes, ( 'mailbox not in config (%s)' % mailbox ) if self.mailbox_selected is not False: - # Close current mailbox so deleted mail is expunged. - # Except one user reports that an explicit expunge is needed with - # his server, or else the mail is never removed from the mailbox. - self.conn.expunge() - self.conn.close() - self.write_oldmailfile(self.mailbox_selected) + self.close_mailbox() self._clear_state() @@ -1281,6 +1648,17 @@ + os.linesep) del self.oldmail[msgid] """ + # Some IMAP servers change the available capabilities after + # authentication, i.e. they present a limited set before login. + # The Python stlib IMAP4 class doesn't take this into account + # and just checks the capabilities immediately after connecting. + # Force a re-check now that we've authenticated. + (typ, dat) = self.conn.capability() + if dat == [None]: + # No response, don't update the stored capabilities + self.log.warn('no post-login CAPABILITY response from server\n') + else: + self.conn.capabilities = tuple(dat[-1].upper().split()) if 'IDLE' in self.conn.capabilities: self.supports_idle = True @@ -1304,7 +1682,7 @@ pass self.conn = None - def go_idle(self, folder, timeout=29*60): + def go_idle(self, folder, timeout=300): """Initiates IMAP's IDLE mode if the server supports it Waits until state of current mailbox changes, and then returns. Returns @@ -1313,11 +1691,11 @@ May throw getmailOperationError if the server refuses the IDLE setup (e.g. if the server does not support IDLE) - Default timeout is the maximum possible idle time according to RFC 2177. + Default timeout is 5 minutes. """ if not self.supports_idle: - self.log.warning('IDLE not supported, so not idling') + self.log.warning('IDLE not supported, so not idling\n') raise getmailOperationError( 'IMAP4 IDLE requested, but not supported by server' ) @@ -1376,12 +1754,7 @@ return try: if self.mailbox_selected is not False: - # Close current mailbox so deleted mail is expunged. - # Except one user reports that an explicit expunge is needed - # with his server, or else the mail is never removed from the - # mailbox. - self.conn.expunge() - self.conn.close() + self.close_mailbox() self.conn.logout() except imaplib.IMAP4.error, o: #raise getmailOperationError('IMAP error (%s)' % o) @@ -1431,13 +1804,14 @@ self.log.trace() msg = IMAPRetrieverBase._getmsgbyid(self, msgid) data = {} - for (name, val) in msg.headers(): + for (name, encoded_value) in msg.headers(): name = name.lower() - val = val.strip() - if name in data: - data[name].append(val) - else: - data[name] = [val] + for (val, encoding) in decode_header(encoded_value): + val = val.strip() + if name in data: + data[name].append(val) + else: + data[name] = [val] try: line = data[self.envrecipname][self.envrecipnum]

@@ -99,6 +99,10 @@ ConfBool(name='delete_dup_msgids', required=False, default=False), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), ) received_from = None received_with = 'POP3-SSL' @@ -200,6 +204,10 @@ ConfBool(name='use_apop', required=False, default=False), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), ) received_with = 'POP3-SSL' @@ -266,6 +274,10 @@ ConfString(name='envelope_recipient'), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), ) received_from = None received_with = 'POP3-SSL' @@ -402,6 +414,10 @@ ConfString(name='move_on_delete', required=False, default=None), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), # imaplib.IMAP4.login_cram_md5() requires the (unimplemented) # .authenticate(), so we can't do this yet (?). ConfBool(name='use_cram_md5', required=False, default=False), @@ -484,6 +500,10 @@ ConfString(name='move_on_delete', required=False, default=None), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), # imaplib.IMAP4.login_cram_md5() requires the (unimplemented) # .authenticate(), so we can't do this yet (?). ConfBool(name='use_cram_md5', required=False, default=False),

@@ -9,6 +9,10 @@ 'decode_crappy_text', 'format_header', 'check_ssl_key_and_cert', + 'check_ca_certs', + 'check_ssl_version', + 'check_ssl_fingerprints', + 'check_ssl_ciphers', 'deliver_maildir', 'eval_bool', 'expand_user_vars', @@ -39,6 +43,18 @@ import grp import getpass import commands +import sys + +# hashlib only present in python2.5, ssl in python2.6; used together +# in SSL functionality below +try: + import ssl +except ImportError: + ssl = None +try: + import hashlib +except ImportError: + hashlib = None # Optional gnome-keyring integration try: @@ -509,6 +525,83 @@ ) return (keyfile, certfile) +####################################### +def check_ca_certs(conf): + ca_certs = conf['ca_certs'] + if ca_certs is not None: + ca_certs = expand_user_vars(ca_certs) + if ssl is None: + raise getmailConfigurationError( + 'specifying ca_certs not supported by this installation of ' + 'Python; requires Python 2.6' + ) + if ca_certs and not os.path.isfile(ca_certs): + raise getmailConfigurationError( + 'optional ca_certs must be path to a valid file' + ) + return ca_certs + +####################################### +def check_ssl_version(conf): + ssl_version = conf['ssl_version'] + if ssl_version is None: + return None + if ssl is None: + raise getmailConfigurationError( + 'specifying ssl_version not supported by this installation of ' + 'Python; requires Python 2.6' + ) + ssl_version = ssl_version.lower() + if ssl_version == 'sslv23': + return ssl.PROTOCOL_SSLv23 + elif ssl_version == 'sslv3': + return ssl.PROTOCOL_SSLv3 + elif ssl_version == 'tlsv1': + return ssl.PROTOCOL_TLSv1 + elif ssl_version == 'tlsv1_1' and 'PROTOCOL_TLSv1_1' in dir(ssl): + return ssl.PROTOCOL_TLSv1_1 + elif ssl_version == 'tlsv1_2' and 'PROTOCOL_TLSv1_2' in dir(ssl): + return ssl.PROTOCOL_TLSv1_2 + else: + raise getmailConfigurationError( + 'unknown or unsupported ssl_version' + ) + +####################################### +def check_ssl_fingerprints(conf): + ssl_fingerprints = conf['ssl_fingerprints'] + if ssl_fingerprints is (): + return () + if ssl is None or hashlib is None: + raise getmailConfigurationError( + 'specifying ssl_fingerprints not supported by this installation of ' + 'Python; requires Python 2.6' + ) + + normalized_fprs = [] + for fpr in ssl_fingerprints: + fpr = fpr.lower().replace(':','') + if len(fpr) != 64: + raise getmailConfigurationError( + 'ssl_fingerprints must each be the SHA256 certificate hash in hex (with or without colons)' + ) + normalized_fprs.append(fpr) + return normalized_fprs + +####################################### +def check_ssl_ciphers(conf): + ssl_ciphers = conf['ssl_ciphers'] + if ssl_ciphers: + if sys.version_info < (2, 7, 0): + raise getmailConfigurationError( + 'specifying ssl_ciphers not supported by this installation of ' + 'Python; requires Python 2.7' + ) + if re.search(r'[^a-zA-z0-9, :!\-+@]', ssl_ciphers): + raise getmailConfigurationError( + 'invalid character in ssl_ciphers' + ) + return ssl_ciphers ####################################### keychain_password = None

[-] [+]	Changed	getmail.changes
@@ -1,4 +1,27 @@ ------------------------------------------------------------------- +Tue Oct 28 17:31:29 UTC 2014 - cs@linux-administrator.com + +- Update to release 4.46.0 + * Version 4.46.0 + -fix --idle checking Python version incorrectly, resulting in incorrect + warning about running with Python < 2.5. Thanks: "Voytek", Krzysztof + Warzecha. + -add missing support for SSL certificate checking in POP3 which broke + POP retrieval in v4.45.0. Requires Python 2.6 or newer. Thanks: "mancha". + + * Version 4.45.0 + -perform hostname-vs-certificate matching of SSL certificate if validating + the certifcate. Thanks: "mancha". + -fix missing plaintext versions of documentation. + + * Version 4.44.0 + -add extended SSL options for IMAP retrievers, allowing certificate + verification and other features. Thanks: Steven Murdoch. + -fix missing plaintext versions of documentation. Thanks: Osamu Aoki. + -fix "Header instance has no attribute 'strip'" error which cropped up + in some configurations. Thanks: Krzysztof Warzecha. + +------------------------------------------------------------------- Mon Aug 26 17:49:38 UTC 2013 - cs@linux-administrator.com - Update to release 4.43.0
[-] [+]	Changed	getmail.spec ^
@@ -11,7 +11,7 @@ # norootforbuild Name: getmail -Version: 4.43.0 +Version: 4.46.0 Release: 0 # Group: Productivity/Networking/Email/Utilities
[-] [+]	Changed	getmail-4.46.0.tar.bz2/PKG-INFO ^
@@ -1,6 +1,6 @@ -Metadata-Version: 1.0 +Metadata-Version: 1.1 Name: getmail -Version: 4.43.0 +Version: 4.46.0 Summary: a mail retrieval, sorting, and delivering system Home-page: http://pyropus.ca/software/getmail/ Author: Charles Cazabon
[-] [+]	Changed	getmail-4.46.0.tar.bz2/docs/CHANGELOG ^
@@ -1,3 +1,25 @@ +Version 4.46.0 +6 April 2014 + -fix --idle checking Python version incorrectly, resulting in incorrect + warning about running with Python < 2.5. Thanks: "Voytek", Krzysztof + Warzecha. + -add missing support for SSL certificate checking in POP3 which broke + POP retrieval in v4.45.0. Requires Python 2.6 or newer. Thanks: "mancha". + +Version 4.45.0 +30 March 2014 + -perform hostname-vs-certificate matching of SSL certificate if validating + the certifcate. Thanks: "mancha". + -fix missing plaintext versions of documentation. + +Version 4.44.0 +22 March 2014 + -add extended SSL options for IMAP retrievers, allowing certificate + verification and other features. Thanks: Steven Murdoch. + -fix missing plaintext versions of documentation. Thanks: Osamu Aoki. + -fix "Header instance has no attribute 'strip'" error which cropped up + in some configurations. Thanks: Krzysztof Warzecha. + Version 4.43.0 25 August 2013 -add IMAP IDLE support. Thanks: Jon Gjengset.
[-] [+]	Changed	getmail-4.46.0.tar.bz2/docs/configuration.html ^
@@ -74,6 +74,8 @@ <ul> <li><a href="configuration.html#conf-retriever-multidrop">What is a "multidrop" mailbox? How do I know if I have one?</a></li> <li><a href="configuration.html#retriever-parameters">Common retriever parameters</a></li> + <li><a href="configuration.html#retriever-ssl-client">SSL Client Parameters</a></li> + <li><a href="configuration.html#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a></li> <li><a href="configuration.html#retriever-simplepop3">SimplePOP3Retriever</a></li> <li><a href="configuration.html#retriever-brokenpop3">BrokenUIDLPOP3Retriever</a></li> <li><a href="configuration.html#retriever-simpleimap">SimpleIMAPRetriever</a></li> @@ -562,6 +564,10 @@ recognized, your Python installation does not have Gnome keyring integration support, or Gnome indicates that the keyring is not available. + If using the OSX keychain on 10.9 "Mavericks" (or later, presumably), + some additional steps may be necessary to make the password available to getmail + via the keychain. See <a href="http://article.gmane.org/gmane.mail.getmail.user/5120">this + posting to the getmail users' mailing list by Alan Schmitt</a> for details. </li> </ul> <p> @@ -630,6 +636,107 @@ </li> </ul> +<h4 id="retriever-ssl-client">SSL Client Parameters</h4> +<p> + All SSL-enabled retriever types also take the following options, to allow + specifying the use of a particular client key and client certificate + in establishing a connection to the server. +</p> +<ul> + <li> + keyfile + (<a href="#parameter-string">string</a>) + — use the specified PEM-formatted key file in the SSL negotiation. + </li> + <li> + certfile + (<a href="#parameter-string">string</a>) + — use the specified PEM-formatted certificate file in the SSL + negotiation. + </li> +</ul> + +<h4 id="retriever-ssl-extra">SSL Certificate Validation and Server Parameters</h4> +<p> + All SSL-enabled POP and IMAP retriever types also take the following options, + allowing you to require validation of the server's SSL certificate, or to check the + server's certificate fingerprint against a known good value, or to control + the specific SSL cipher used during the connection. +</p> +<p> + <strong>Note: using these features, including server certificate validation, + requires using Python 2.6 or Python 2.7 or higher with getmail.</strong> + If you use an earlier version of Python, these features will not work, and + no server certificate validation will be performed. + Also note that these features are not currently implemented for SPDS + retrievers; I would be interested in hearing from SPDS users who desire + these features. +</p> +<ul> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — advanced option to perform validation of the server's SSL + certificate. Specify the path to a PEM-formatted list of 1 or more + valid and trusted root certification authority (CA) certificates. + <strong>Note: this option is only available with Python 2.6 or higher.</strong> + <br /> + To find out which root CA is used to sign the chain of certificates for + a given server, you can run + <pre class="example"> +openssl s_client -showcerts -connect HOST:PORT < /dev/null 2>/dev/null \ + \| grep '^[[:space:]]*i:' \| tail -n 1 +</pre> + If the server's certificate cannot be validated based upon the supplied + trusted root certificates, getmail will abort the connection. + <br /> + Root certificates are not supplied with getmail; your OS probably installs a set + by default for use by the system, or you may wish to use a specific set of + trusted root certificates provided by your employer or a trusted third + party. Common locations for OS-supplied SSL root certification authority + certificates include: + <ul> + <li>Linux (Debian, Ubuntu, Arch, SuSE): <pre class="file">/etc/ssl/certs/</pre></li> + <li>Linux (RedHat, Fedora, CentOS): <pre class="file">/etc/pki/tls/certs/</pre></li> + <li>FreeBSD: <pre class="file">/usr/local/share/certs/</pre></li> + <li>OpenBSD: <pre class="file">/etc/ssl/</pre></li> + <li>OSX: <pre class="file">/System/Library/OpenSSL/certs/</pre></li> + <li>Windows: ask Microsoft</li> + </ul> + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — advanced option to control which SSL cipher algorithms will be + allowed to proceed. See the + <a href="http://www.openssl.org/docs/apps/ciphers.html">Open SSL documentation</a> + for details. + If the specified setting results in no possible ciphers available, + getmail will abort the connection. + <strong>Note: this option is only available with Python 2.7 or higher.</strong> + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — advanced option to control which SSL version getmail tries to + use to connect to the server; the default is "sslv23". Another + useful value is probably "sslv3". The available option values + are taken from the Python ssl module. + <strong>Note: this option is only available with Python 2.6 or higher.</strong> + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — advanced option to notice when the server's SSL certificate + changes. Supply a list of one or more SHA256 certificate fingerprints, + and getmail will confirm whether the server's certificate fingerprint is + in the list of allowed fingerprints; if it is not, getmail will abort + the connection. Getmail will log the fingerprint of the server's certificate + if you supply the <span class="file">--fingerprint</span> commandline option. + <strong>Note: this option is only available with Python 2.6 or higher.</strong> + </li> +</ul> + <h4 id="retriever-simplepop3">SimplePOP3Retriever</h4> <p> The SimplePOP3Retriever class takes the @@ -742,16 +849,28 @@ for definition. </li> <li> - keyfile + ca_certs (<a href="#parameter-string">string</a>) - — use the specified PEM-formatted key file in the SSL negotiation. - Note that no certificate or key validation is done. + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition </li> <li> - certfile + ssl_ciphers (<a href="#parameter-string">string</a>) - — use the specified PEM-formatted certificate file in the SSL - negotiation. Note that no certificate or key validation is done. + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition </li> </ul> @@ -773,16 +892,40 @@ keyfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> <li> certfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> </ul> <h4 id="retriever-simpleimapssl">SimpleIMAPSSLRetriever</h4> @@ -810,16 +953,40 @@ keyfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> <li> certfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> </ul> <h4 id="retriever-multidroppop3">MultidropPOP3Retriever</h4> @@ -896,16 +1063,40 @@ keyfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> <li> certfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> </ul> <h4 id="retriever-multidropsdps">MultidropSDPSRetriever</h4> @@ -1005,16 +1196,40 @@ keyfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> <li> certfile (<a href="#parameter-string">string</a>) — see - <a href="#retriever-simplepop3ssl">SimplePOP3SSLRetriever</a> + <a href="#retriever-ssl-client">SSL Client Parameters</a> for definition. </li> + <li> + ca_certs + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_ciphers + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_version + (<a href="#parameter-string">string</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> + <li> + ssl_fingerprints + (<a href="#parameter-tuplestrings">tuple of quoted strings</a>) + — see <a href="#retriever-ssl-extra">SSL Certificate Validation and Server Parameters</a> + for definition + </li> </ul> <h3 id="retriever-examples">Retriever examples</h3> @@ -2732,7 +2947,7 @@ <p> If you are using a single getmailrc file with an IMAP server that understands the IDLE extension from <a href="http://www.rfc-editor.org/rfc/rfc2177.txt">RFC 2177</a>, - you can use the --rcfile=<span class="meta">MAILBOX</span> option to specify + you can use the --idle=<span class="meta">MAILBOX</span> option to specify that getmail should wait on the server to notify getmail of new mail in the specified mailbox after getmail is finished retrieving mail. </p>
[-] [+]	Added	getmail-4.46.0.tar.bz2/docs/configuration.txt ^
@@ -0,0 +1,1629 @@ +getmail documentation + + This is the documentation for getmail version 4. Version 4 includes + numerous changes from version 3.x; if you are using getmail version 3, + please refer to the documentation included with that version of the + software. + + getmail is Copyright © 1998-2009 Charles Cazabon. + + getmail is licensed under the GNU General Public License version 2 + (only). If you wish to obtain a license to distribute getmail under + other terms, please contact me directly. + +Table of Contents + + * getmail documentation + * + + getmail documentation + + + o Features + o Differences from previous versions + o Requirements + o Obtaining getmail + o Installing getmail + o getmail mailing lists + * getmail configuration + * + + Configuring getmail + + + o Creating a getmail rc file + o + # Parameter types and formats + # + @ string + @ integer + @ boolean + @ tuple of quoted strings + @ tuple of integers + @ tuple of 2-tuples + # Creating the [retriever] section + # + @ What is a "multidrop" mailbox? How do I know if + I have one? + @ Common retriever parameters + @ SSL Client Parameters + @ SSL Certificate Validation and Server + Parameters + @ SimplePOP3Retriever + @ BrokenUIDLPOP3Retriever + @ SimpleIMAPRetriever + @ SimplePOP3SSLRetriever + @ BrokenUIDLPOP3SSLRetriever + @ SimpleIMAPSSLRetriever + @ MultidropPOP3Retriever + @ MultidropPOP3SSLRetriever + @ MultidropSDPSRetriever + @ MultidropIMAPRetriever + @ MultidropIMAPSSLRetriever + # Retriever examples + # Creating the [destination] section + # + @ Maildir + @ Mboxrd + @ MDA_external + @ MultiDestination + @ MultiSorter + @ MultiGuesser + @ MDA_qmaillocal + # Creating the [options] section + # + @ [options] example + # Creating the [filter-something] sections + # + @ Filter_classifier + @ Filter_external + @ Filter_TMDA + @ [filter-something] examples + # getmail rc file examples + + Running getmail + + + o Commandline options + o Using getmail as an MDA + o + # Using the getmail_maildir MDA + # + @ Example + # Using the getmail_mbox MDA + # + @ Example + o Using getmail_fetch to retrieve mail from scripts + * getmail troubleshooting + * + + Troubleshooting problems + + + o Error messages + o Warning messages + o Unexpected Behaviour + * getmail frequently-asked questions (FAQs) + * + + Frequently-Asked Questions (FAQs) + + + o About getmail + o Configuring getmail + o How do I … + o Using getmail with other software + o I think I found this bug in getmail … + +Configuring getmail + + Once getmail is installed, you need to configure it before you can + retrieve mail with it. Follow these steps: + 1. Create a data/configuration directory. The default is + $HOME/.getmail/. If you choose a different location, you will need + to specify it on the getmail command line. In general, other users + should not be able to read the contents of this directory, so you + should set the permissions on it appropriately. +mkdir -m 0700 $HOME/.getmail + + 2. Create a configuration file in the configuration/data directory. + The default name is getmailrc. If you choose a different filename, + you will need to specify it on the getmail command line. If you + want to retrieve mail from more than one mail account, you will + need to create a separate rc file for each account getmail should + retrieve mail from. + +Creating a getmail rc file + + The configuration file format is designed to be easy to understand + (both for getmail, and for the user). It is broken down into small + sections of related parameters by section headers which appear on lines + by themselves, enclosed in square brackets, like this: +[section name] + + Each section contains a series of parameters, declared as follows: +parameter_name = parameter_value + + A parameter value, if necessary, can span multiple lines. To indicate + that the second and subsequent lines form a continuation of the + previous line, they need to begin with leading whitespace, like this: +first_parameter = value + first parameter value continues here +second_parameter = value + + You can annotate your configuration files with comments by putting them + on lines which begin with a pound sign, like this: +first_parameter = value +# I chose this value because of etc. +second_parameter = value + + Each rc file requires at least two specific sections. The first is + retriever, which tells getmail about the mail account to retrieve + messages from. The second is destination, which tells getmail what to + do with the retrieved messages. There is also an optional section named + options , which gives getmail general configuration information (such + as whether to log its actions to a file), and other sections can be + used to tell getmail to filter retrieved messages through other + programs, or to deliver messages for particular users in a particular + way. + +Parameter types and formats + + Several different types of parameters are used in getmail rc files: + * string + * integer + * boolean + * tuple of quoted strings + * tuple of integers + * tuple of 2-tuples + + Each parameter type has a specific format that must be used to + represent it in the getmail rc file. They are explained below. Each + parameter documented later specifies its type explicitly. + +string + + Specify a string parameter value with no special syntax: +parameter = my value + +integer + + Specify an integer parameter value with no special syntax: +parameter = 4150 + +boolean + + A boolean parameter is true or false; you can specify its value with + the (case-insensitive) words "true" and "false". The values "yes", "on" + and 1 are accepted as equivalent to "true", while values "no", "off" + and 0 are accepted as equivalent to "false". Some examples: +parameter = True +parameter = false +parameter = NO +parameter = 1 + +tuple of quoted strings + + A tuple of quoted strings is essentially a list of strings, with each + string surrounded by matching double- or single-quote characters to + indicate where it begins and ends. The list must be surrounded by open- + and close-parenthesis characters. A tuple may have to be a specific + number of strings; for instance, a "2-tuple" must consist of two quoted + strings, while a "4-tuple" must have exactly four. In most cases, the + number of strings is not required to be a specific number, and it will + not be specified in this fashion. + + In general, a tuple of quoted strings parameter values should look like + this: +parameter = ('first string', 'second string', + "third string that contains a ' character") + + However, tuples of 0 or 1 strings require special treatment. The empty + tuple is specified with just the open- and close-parenthesis + characters: +parameter = () + + A tuple containing a single quoted string requires a comma to indicate + it is a tuple: +parameter = ("single string", ) + +tuple of integers + + This is very similar to a tuple of quoted strings, above, minus the + quotes. Some examples: +parameter = (1, 2, 3, 4, 5) +parameter = (37, ) +parameter = () + +tuple of 2-tuples + + This is a tuple of items, each of which is a 2-tuple of quoted strings. + You can think of this as a list of pairs of quoted strings. +# Three pairs +parameter = ( + ("first-a", "first-b"), + ("second-a", "second-b"), + ("third-a", "third-b"), + ) +# One pair +parameter = ( + ("lone-a", "lone-b"), + ) + +Creating the [retriever] section + + The retriever section of the rc file tells getmail what mail account to + retrieve mail from, and how to access that account. Begin with the + section header line as follows: +[retriever] + + Then, include a type string parameter to tell getmail what type of mail + retriever to use to retrieve mail from this account. The possible + values are: + * SimplePOP3Retriever — for single-user POP3 mail accounts. + * BrokenUIDLPOP3Retriever — for broken POP3 servers that do not + support the UIDL command, or which do not uniquely identify + messages; this provides basic support for single-user POP3 mail + accounts on such servers. + * SimpleIMAPRetriever — for single-user IMAP mail accounts. + * SimplePOP3SSLRetriever — same as SimplePOP3Retriever, but uses SSL + encryption. + * BrokenUIDLPOP3SSLRetriever — same as BrokenUIDLPOP3Retriever, but + uses SSL encryption. + * SimpleIMAPSSLRetriever — same as SimpleIMAPRetriever, but uses SSL + encryption. + * MultidropPOP3Retriever — for domain mailbox (multidrop) POP3 mail + accounts. + * MultidropPOP3SSLRetriever — same as MultidropPOP3Retriever, but + uses SSL encryption. + * MultidropSDPSRetriever — for domain mailbox SDPS mail accounts, as + provided by the UK ISP Demon. + * MultidropIMAPRetriever — for domain mailbox (multidrop) IMAP mail + accounts. + * MultidropIMAPSSLRetriever — same as MultidropIMAPRetriever, but + uses SSL encryption. + +What is a "multidrop" mailbox? How do I know if I have one? + + Some ISPs, mailhosts, and other service providers provide a mail + service they refer to as a "domain mailbox" or "multidrop mailbox". + This is where they register a domain for you, and mail addressed to any + local-part in that domain ends up in a single mailbox accessible via + POP3, with the message envelope (envelope sender address and envelope + recipient address) recorded properly in the message header, so that it + can be re-constructed after you retrieve the messages with POP3 or + IMAP. The primary benefit of this is that you can run your own MTA + (qmail, Postfix, sendmail, Exchange, etc.) for your domain without + having to have an SMTP daemon listening at a static IP address. + + Unfortunately, a lot of what is advertised and sold as multidrop + service really isn't. In many cases, the envelope recipient address of + the message is not properly recorded, so the envelope information is + lost and cannot be reconstructed. If the envelope isn't properly + preserved, it isn't a domain mailbox, and you therefore can't use a + multidrop retriever with that mailbox. + + To determine if you have a multidrop mailbox, check the following list: + if any of these items are not true, you do not have a multidrop + mailbox. + * the mailbox must receive one copy of the message for each envelope + recipient in the domain; if the message was addressed to three + local-parts in the domain, the mailbox must receive three separate + copies of the message. + * the envelope sender address must be recorded in a header field + named Return-Path at the top of the message. If the message + (incorrectly) already contained such a header field, it must be + deleted before the envelope sender address is recorded. + * the envelope recipient address must be recorded in a new header + field. These may be named various things, but are commonly + Delivered-To, X-Envelope-To, and similar values. In the case of + messages which had multiple recipients in the domain, this must be + a single address, reflecting the particular recipient of this copy + of the message. Note that this field (and the envelope recipient + address) are not related to informational header fields created by + the originating MUA, like To or cc. + + If you're not sure whether you have a multidrop mailbox, you probably + don't. You probably want to use SimplePOP3Retriever (for POP3 mail + accounts) or SimpleIMAPRetriever (for IMAP mail accounts) retrievers. + + Specify the mail account type with one of the above values, like this: +type = typename + + Then, include lines for any parameters and their values which are + required by the retriever. The parameters and their types are + documented below. + +Common retriever parameters + + All retriever types take several common required parameters: + * server (string) — the name or IP address of the server to retrieve + mail from + * username (string) — username to provide when logging in to the mail + server + + All retriever types also take several optional parameters: + * port (integer) — the TCP port number to connect to. If not + provided, the default is a port appropriate for the protocol (110 + for POP3, etc.) + * password (string) — password to use when logging in to the mail + server. If not using Kerberos authentication -- see below -- + getmail gets the password credential for the POP/IMAP server in one + of the following ways: + 1. from the password configuration item in the getmailrc file + 2. on Mac OS X only, from the OS X keychain + 3. on systems with Gnome keyring support, from the default Gnome + keyring + 4. if not found via any of the above methods, getmail will prompt + for the password when run + To store your POP/IMAP account password into the Gnome keyring, + ensure the password is not provided in the getmailrc file, and run + getmail with the special option --store-password-in-gnome-keyring; + getmail will run, prompt you for the password, store it in the + Gnome keyring, and exit without retrieving mail. If this option is + not recognized, your Python installation does not have Gnome + keyring integration support, or Gnome indicates that the keyring is + not available. If using the OSX keychain on 10.9 "Mavericks" (or + later, presumably), some additional steps may be necessary to make + the password available to getmail via the keychain. See this + posting to the getmail users' mailing list by Alan Schmitt for + details. + + All IMAP retriever types also take the following optional parameters: + * mailboxes (tuple of quoted strings) — a list of mailbox paths to + retrieve mail from, expressed as a Python tuple. If not specified, + the default is to retrieve mail from the mail folder named INBOX. + You might want to retrieve messages from several different mail + folders, using a configuration like this: +mailboxes = ("INBOX", "INBOX.spam", + "mailing-lists.model-railroading") + + Note that the format for hierarchical folder names is determined by + the IMAP server, not by getmail. Consult your server's + documentation or postmaster if you're unsure what form your server + uses. If your mailbox names contain non-ASCII characters, ensure + that your getmailrc file is stored with UTF-8 encoding so that + getmail can correctly determine the unicode character names that + need to be quoted in IMAP's modified UTF-7 encoding; if you do not + do this, the mailbox names will not match what the server expects + them to be, or will cause UnicodeErrors when attempting to load + your getmailrc file. As a special case, in getmail version 4.29.0 + and later, the unquoted base (non-tuple) value ALL (case-sensitive) + means to retrieve mail from all selectable IMAP mailboxes in the + account. To retrieve messages from all mailboxes, you would use: +mailboxes = ALL + + * use_peek (boolean) — whether to use PEEK to retrieve the message; + the default is True. IMAP servers typically mark a message as seen + if PEEK is not used to retrieve the message content. Versions of + getmail prior to 4.26.0 did not use PEEK to retrieve messages. + * move_on_delete (string) — if set, messages are moved to the named + mail folder before being deleted from their original location. Note + that if you configure getmail not to delete retrieved messages (the + default behaviour), they will not be moved at all. + * use_kerberos (boolean) — whether to use Kerberos authentication + with the IMAP server. If not set, normal password-based + authenticaion is used. Note that when you use Kerberos + authentication, it is up to you to ensure you have a valid Kerberos + ticket (perhaps by running a ticket-renewing agent such as kstart + or similar). This feature requires that a recent version of + pykerberos with GSS support is installed; check your OS + distribution or see http://honk.sigxcpu.org/projects/pykerberos/" + for details. + +SSL Client Parameters + + All SSL-enabled retriever types also take the following options, to + allow specifying the use of a particular client key and client + certificate in establishing a connection to the server. + * keyfile (string) — use the specified PEM-formatted key file in the + SSL negotiation. + * certfile (string) — use the specified PEM-formatted certificate + file in the SSL negotiation. + +SSL Certificate Validation and Server Parameters + + All SSL-enabled POP and IMAP retriever types also take the following + options, allowing you to require validation of the server's SSL + certificate, or to check the server's certificate fingerprint against a + known good value, or to control the specific SSL cipher used during the + connection. + + Note: using these features, including server certificate validation, + requires using Python 2.6 or Python 2.7 or higher with getmail. If you + use an earlier version of Python, these features will not work, and no + server certificate validation will be performed. Also note that these + features are not currently implemented for SPDS retrievers; I would be + interested in hearing from SPDS users who desire these features. + * ca_certs (string) — advanced option to perform validation of the + server's SSL certificate. Specify the path to a PEM-formatted list + of 1 or more valid and trusted root certification authority (CA) + certificates. Note: this option is only available with Python 2.6 + or higher. + To find out which root CA is used to sign the chain of certificates + for a given server, you can run +openssl s_client -showcerts -connect HOST:PORT < /dev/null 2>/dev/null \ + \| grep '^[[:space:]]i:' \| tail -n 1 + + If the server's certificate cannot be validated based upon the + supplied trusted root certificates, getmail will abort the + connection. + Root certificates are not supplied with getmail; your OS probably + installs a set by default for use by the system, or you may wish to + use a specific set of trusted root certificates provided by your + employer or a trusted third party. Common locations for OS-supplied + SSL root certification authority certificates include: + + Linux (Debian, Ubuntu, Arch, SuSE): +/etc/ssl/certs/ + + Linux (RedHat, Fedora, CentOS): +/etc/pki/tls/certs/ + + FreeBSD: +/usr/local/share/certs/ + + OpenBSD: +/etc/ssl/ + + OSX: +/System/Library/OpenSSL/certs/ + + Windows: ask Microsoft + ssl_ciphers (string) — advanced option to control which SSL cipher + algorithms will be allowed to proceed. See the Open SSL + documentation for details. If the specified setting results in no + possible ciphers available, getmail will abort the connection. + Note: this option is only available with Python 2.7 or higher. + * ssl_version (string) — advanced option to control which SSL version + getmail tries to use to connect to the server; the default is + "sslv23". Another useful value is probably "sslv3". The available + option values are taken from the Python ssl module. Note: this + option is only available with Python 2.6 or higher. + * ssl_fingerprints (tuple of quoted strings) — advanced option to + notice when the server's SSL certificate changes. Supply a list of + one or more SHA256 certificate fingerprints, and getmail will + confirm whether the server's certificate fingerprint is in the list + of allowed fingerprints; if it is not, getmail will abort the + connection. Getmail will log the fingerprint of the server's + certificate if you supply the --fingerprint commandline option. + Note: this option is only available with Python 2.6 or higher. + +SimplePOP3Retriever + + The SimplePOP3Retriever class takes the common retriever parameters + above, plus the following optional parameters: + * use_apop (boolean) — if set to True, getmail will use APOP-style + authentication to log in to the server instead of normal USER/PASS + authentication. This is not supported by many POP3 servers. Note + that APOP adds much less security than might be supposed; + weaknesses in its hashing algorithm mean that an attacker can + recover the first three characters of the password after snooping + on only a few hundred authentications between a client and server — + see http://www.securityfocus.com/archive/1/464477/30/0/threaded for + details. The default is False. + * timeout (integer) — how long (in seconds) to wait for socket + operations to complete before considering them failed. If not + specified, the default is 180 seconds. You may need to increase + this value in particularly poor networking conditions. + * delete_dup_msgids (boolean) — if set to True, and the POP3 server + identifies multiple messages as having the same "unique" + identifier, all but the first will be deleted without retrieving + them. + +BrokenUIDLPOP3Retriever + + This retriever class is intended only for use with broken POP3 servers + that either do not implement the UIDL command, or which do not properly + assign unique identifiers to messages (preventing getmail from + determining which messages it has seen before). It will identify every + message in the mailbox as a new message, and therefore if you use this + retriever class and opt not to delete messages after retrieval, it will + retrieve those messages again the next time getmail is run. Use this + retriever class only if your mailbox is hosted on such a broken POP3 + server, and the server does not provide another means of getmail + accessing it (i.e., IMAP). + + The BrokenUIDLPOP3Retriever class takes the common retriever parameters + above, plus the following optional parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * timeout (integer) — see SimplePOP3Retriever for definition. + +SimpleIMAPRetriever + + The SimpleIMAPRetriever class takes the common retriever parameters + above, plus the following optional parameters: + * timeout (integer) — see SimplePOP3Retriever for definition. + +SimplePOP3SSLRetriever + + The SimplePOP3SSLRetriever class takes the common retriever parameters + above, plus the following optional parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * delete_dup_msgids (boolean) — see SimplePOP3Retriever for + definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +BrokenUIDLPOP3SSLRetriever + + The BrokenUIDLPOP3SSLRetriever class takes the common retriever + parameters above, plus the following optional parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * keyfile (string) — see SSL Client Parameters for definition. + * certfile (string) — see SSL Client Parameters for definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +SimpleIMAPSSLRetriever + + The SimpleIMAPSSLRetriever class takes the common retriever parameters + above, plus the following optional parameters: + * mailboxes (tuple of quoted strings) — see common retriever + parameters for definition. + * move_on_delete (string) — see SimpleIMAPRetriever for definition. + * keyfile (string) — see SSL Client Parameters for definition. + * certfile (string) — see SSL Client Parameters for definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +MultidropPOP3Retriever + + The MultidropPOP3Retriever class takes the common retriever parameters + above, plus the following required parameter: + * envelope_recipient (string) — the name and position of the header + field which records the envelope recipient address. This is set to + a value of the form field_name : field_position . The first + (topmost) Delivered-To: header field would be specified as: +envelope_recipient = delivered-to:1 + + The MultidropPOP3Retriever also takes the following optional + parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * timeout (integer) — see SimplePOP3Retriever for definition. + +MultidropPOP3SSLRetriever + + The MultidropPOP3SSLRetriever class takes the common retriever + parameters above, plus the following required parameter: + * envelope_recipient (string) — see MultidropPOP3Retriever for + definition. + + The MultidropPOP3SSLRetriever class alo takes the following optional + parameters: + * use_apop (boolean) — see SimplePOP3Retriever for definition. + * keyfile (string) — see SSL Client Parameters for definition. + * certfile (string) — see SSL Client Parameters for definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +MultidropSDPSRetriever + + The MultidropSDPSRetriever class takes the common retriever parameters + above, plus the following optional parameters: + * timeout (integer) — see SimplePOP3Retriever for definition. + +MultidropIMAPRetriever + + The MultidropIMAPRetriever class takes the common retriever parameters + above, plus the following required parameter: + * envelope_recipient (string) — see MultidropPOP3Retriever for + definition. + + The MultidropIMAPRetriever class also takes the following optional + parameters: + * timeout (integer) — see SimplePOP3Retriever for definition. + * mailboxes (tuple of quoted strings) — see common retriever + parameters for definition. + * move_on_delete (string) — see SimpleIMAPRetriever for definition. + +MultidropIMAPSSLRetriever + + The MultidropIMAPSSLRetriever class takes the common retriever + parameters above, plus the following required parameter: + * envelope_recipient (string) — see MultidropPOP3Retriever for + definition. + + The MultidropIMAPSSLRetriever class also takes following optional + parameters: + * mailboxes (tuple of quoted strings) — see common retriever + parameters for definition. + * move_on_delete (string) — see SimpleIMAPRetriever for definition. + * keyfile (string) — see SSL Client Parameters for definition. + * certfile (string) — see SSL Client Parameters for definition. + * ca_certs (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_ciphers (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_version (string) — see SSL Certificate Validation and Server + Parameters for definition + * ssl_fingerprints (tuple of quoted strings) — see SSL Certificate + Validation and Server Parameters for definition + +Retriever examples + + A typical POP3 mail account (the basic kind of mailbox provided by most + internet service providers (ISPs)) would use a retriever configuration + like this: +[retriever] +type = SimplePOP3Retriever +server = popmail.isp.example.net +username = account_name +password = my_mail_password + + If your ISP provides POP3 access on a non-standard port number, you + would need to include the port parameter: +[retriever] +type = SimplePOP3Retriever +server = popmail.isp.example.net +port = 8110 +username = account_name +password = my_mail_password + + If your ISP provides POP3-over-SSL and you wanted to use that, your + retriever configuration might look like this: +[retriever] +type = SimplePOP3SSLRetriever +server = popmail.isp.example.net +username = account_name +password = my_mail_password + + If you have an IMAP mail account and want to retrieve messages from + several mail folders under that account, and you want to move messages + to a special folder when deleting them, you would use a retriever + configuration like this: +[retriever] +type = SimpleIMAPRetriever +server = imapmail.isp.example.net +username = account_name +password = my_mail_password +mailboxes = ("INBOX", "lists.unix", "lists.getmail") +move_on_delete = mail.deleted + + If you are retrieving your company's mail from a domain POP3 mailbox + for delivery to multiple local users, you might use a retriever + configuration like this: +[retriever] +type = MultidropPOP3Retriever +server = imapmail.isp.example.net +username = account_name +password = company_maildrop_password +envelope_recipient = delivered-to:1 + +Creating the [destination] section + + The destination section of the rc file tells getmail what to do with + retrieved messages. Begin with the section header line as follows: +[destination] + + Then, include a type string parameter to tell getmail what type of mail + destination this is. The possible values are: + * Maildir — deliver all messages to a local qmail-style maildir + * Mboxrd — deliver all messages to a local mboxrd-format mbox file + with fcntl-type locking. + * MDA_external — use an external message delivery agent (MDA) to + deliver messages. Typical MDAs include maildrop, procmail, and + others. + * MultiDestination — unconditionally deliver messages to multiple + destinations (maildirs, mbox files, external MDAs, or other + destinations). + * MultiSorter — sort messages according to the envelope recipient + (requires a domain mailbox retriever) and deliver to a variety of + maildirs, mbox files, external MDAs, or other destinations based on + regular expressions matching the recipient address of each message. + Messages not matching any of the regular expressions are delivered + to a default "postmaster" destination. + * MultiGuesser — sort messages according to getmail's best guess at + what the envelope recipient of the message might have been, and + deliver to a variety of maildirs, mbox files, external MDAs, or + other destinations based on regular expressions matching those + addresses. Messages not matching any of the regular expressions are + delivered to a default "postmaster" destination. + * MDA_qmaillocal — use qmail-local to deliver messages according to + instructions in a .qmail file. + +Maildir + + The Maildir destination delivers to a qmail-style maildir. The maildir + must already exist, and must contain all of the subdirectories required + by the maildir format. getmail will not create the maildir if it does + not exist. If you're not familiar with the maildir format, the + requirements in a nutshell are: it must be a directory containing three + writable subdirectories cur, new, and tmp, and they must all reside on + the same filesystem. + + The Maildir destination takes one required parameter: + * path (string) — the path to the maildir, ending in slash (/). This + value will be expanded for leading ~ or ~USER and environment + variables in the form $VARNAME or ${VARNAME}. You might want to + deliver messages to a maildir named Maildir in your home directory; + you could do this with a configuration like this: +[destination] +type = Maildir +path = ~/Maildir/ + + The Maildir destination also takes two optional parameters: + * user (string) — on Unix-like systems, if supplied, getmail will + change the effective UID to that of the named user before + delivering messages to the maildir. Note that this typically + requires root privileges. getmail will not deliver to maildirs as + root, so this "optional" parameter is required in that situation. + * filemode (string) — if supplied, getmail will cause the delivered + message files in the maildir to have at most these permissions + (given in standard Unix octal notation). Note that the current + umask is masked out of the given value at file creation time. The + default value, which should be appropriate for most users, is + "0600". + +Mboxrd + + The Mboxrd destination delivers to an mboxrd-format mbox file with + either fcntl-type (lockf) or flock-type file locking. The file must + already exist and appear to be a valid mboxrd file before getmail will + try to deliver to it — getmail will not create the file if it does not + exist. If you want to create a new mboxrd file for getmail to use, + simply create a completely empty (0-byte) file. + + You must ensure that all other programs accessing any the mbox file + expect mboxrd-format mbox files and the same type of file locking that + you configure getmail to use; failure to do so can cause mbox + corruption. If you do not know what type of file locking your system + expects, ask your system administrator. If you are the system + administrator and don't know what type of file locking your system + expects, do not use Mboxrd files; use Maildirs instead. Note that + delivering to mbox files over NFS can be unreliable and should be + avoided; this is the case with any MDA. + + The Mboxrd destination takes one required parameter: + * path (string) — the path to the mbox file. This value will be + expanded for leading ~ or ~USER and environment variables in the + form $VARNAME or ${VARNAME}. You might want to deliver messages to + an mbox file named inbox in your home directory; you could do this + with a configuration like this: +[destination] +type = Mboxrd +path = ~/inbox + + The Mboxrd destination also takes two optional parameters: + * user (string) — on Unix-like systems, if supplied, getmail will + change the effective UID to that of the named user before + delivering messages to the mboxrd file. Note that this typically + requires root privileges. getmail will not deliver to mbox files as + root, so this "optional" parameter is required in that situation. + * locktype (string) — which type of file locking to use; may be + "lockf" (for fcntl locking) or "flock". The default in getmail + 4.7.0 and later is lockf. + +MDA_external + + MDA_external delivers messages by running an external program (known as + a message delivery agent, or MDA) and feeding it the message on its + standard input. Some typical MDAs include maildrop and procmail. + + The MDA_external destination takes one required parameter: + * path (string) — the path to the command to run. This value will be + expanded for leading ~ or ~USER and environment variables in the + form $VARNAME or ${VARNAME}. + + The MDA_external destination also takes several optional parameters: + * arguments (tuple of quoted strings) — arguments to be supplied to + the command. The following substrings will be substituted with the + equivalent values from the message: + + %(sender) — envelope return-path address + If the message is retrieved with a multidrop retriever class, the + message recipient (and parts of it) are also available with the + following replacement substrings: + + %(recipient) — envelope recipient address + + %(local) — local-part of the envelope recipient address + + %(domain) — domain-part of the envelope recipient address + + %(mailbox) — the IMAP mailbox name the message was retrieved + from; for POP, this will be empty + The default value of the arguments parameter is (), so no arguments + are supplied to the command. + * unixfrom (boolean) — whether to include a Unix-style mbox From_ + line at the beginning of the message supplied to the command. + Defaults to false. Some MDAs expect such a line to be present and + will fail to operate if it is missing. + * user (string) — if supplied, getmail will change the effective UID + to that of the named user. Note that this typically requires root + privileges. + * group (string) — if supplied, getmail will change the effective GID + to that of the named group. Note that this typically requires root + privileges. + * allow_root_commands (boolean) — if set, getmail will run external + commands even if it is currently running with root privileges. The + default is false, which causes getmail to raise an exception if it + is asked to run an external command as root. Note that setting this + option has serious security implications. Don't use it if you don't + know what you're doing. I strongly recommend against running + external processes as root. + * ignore_stderr (boolean) — if set, getmail will not consider it an + error if the program writes to stderr. The default is false, which + causes getmail to consider the delivery failed and leave the + message on the server, proceeding to the next message. This + prevents loss of mail if the MDA writes to stderr but fails to exit + nonzero when it encounters an error. Note that setting this option + has serious implications; some MDAs can fail to deliver a message + but still exit 0, which can cause loss of mail if this option is + set. Only change this setting if you are confident your MDA always + exits nonzero on error. + + A basic invocation of an external MDA might look like this: +[destination] +type = MDA_external +path = /path/to/mymda +arguments = ("--log-errors", ) + + Something more complex might look like this: +[destination] +type = MDA_external +path = /path/to/mymda +# Switch to fred's UID and the mail group GID before delivering his mail +user = fred +group = mail +arguments = ("--strip-forbidden-attachments", "--recipient=%(recipient)") + +MultiDestination + + MultiDestination doesn't do any message deliveries itself; instead, it + lets you specify a list of one or more other destinations which it will + pass each message to. You can use this to deliver each message to + several different destinations. + + The MultiDestination destination takes one required parameter: + * destinations (tuple of quoted strings) — the destinations which the + messages will be passed to. A destination is a string that refers + to another configuration file section by name (shortcuts for + maildirs and mboxrd files are also provided; see below), like this: +destinations = ('[other-destination-1]', '[other-destination-2]') + +[other-destination-1] +type = Mboxrd +path = /var/spool/mail/alice +user = alice + +[other-destination-2] +type = Maildir +path = /home/joe/Maildir/ +user = joe + + Because Maildir and Mboxrd destinations are common, you can specify + them directly as a shortcut if they do not require a user + parameter. If the string (after expansion; see below) starts with a + dot or slash and ends with a slash, it specifies the path of a + Maildir destination, while if it starts with a dot or a slash and + does not end with a slash, it specifies the path of a Mboxrd + destination. + For instance, you can deliver mail to two maildirs with the + following: +destinations = ('~/Mail/inbox/', '~/Mail/archive/current/') + + Each destination string is first expanded for leading ~ or ~USER + and environment variables in the form $VARNAME or ${VARNAME}. + + Some examples: + * To deliver to a maildir named Maildir in the home directory of user + jeff, when getmail is run as that user: +[destination] +type = MultiDestination +destinations = ("~jeff/Maildir/", ) + + * To deliver to an mboxrd file: +[destination] +type = MultiDestination +destinations = ("/var/spool/mail/alice", ) + + * To deliver with an external MDA: +[destination] +type = MultiDestination +destinations = ("[procmail-as-bob]", ) + +[procmail-as-bob] +type = MDA_external +path = /path/to/procmail +arguments = ('~bob/.procmailrc', '-f', '%(sender)') +user = bob + + Of course, the whole point of MultiDestination is to allow you to + specify multiple destinations, like this: +[destination] +type = MultiDestination +destinations = ( + "~jeff/Mail/inbox", + "[procmail-as-jeff]", + "/var/mail-archive/incoming" + ) + +[procmail-as-jeff] +type = MDA_external +path = /path/to/procmail +arguments = ('~jeff/.procmailrc', '-f', '%(sender)') +user = jeff + +MultiSorter + + MultiSorter compares the envelope recipient address of messages against + a list of user-supplied regular expressions and delivers the message to + the destination (maildir, mboxrd file, or other) associated with any + matching patterns. A message can match multiple patterns and therefore + be delivered to multiple matching destinations. Any message which + matches none of the patterns is delivered to a default destination for + the postmaster. + + Because MultiSorter requires the envelope recipient to operate, it must + be used with a domain mailbox retriever. If you instead want to do some + basic message sorting based on getmail's best guess as to the envelope + recipient of the message, see the MultiGuesser destination class below. + + The MultiSorter destination takes one required parameter: + * default (string) — the destination for messages which aren't + matched by any of the "locals" regular expressions. The destination + can be a maildir, mboxrd file, or other destination. See + MultiDestination for an explanation of how the type of destination + is interpreted from this value. + + The MultiSorter destination also takes one optional parameter: + * locals (tuple of 2-tuples) — zero or more regular expression – + destination pairs. Messages will be delivered to each destination + for which the envelope recipient matches the given regular + expression. The regular expression and destination are supplied as + two quoted strings in a tuple; locals is then a tuple of such pairs + of strings. Destinations are specified in the same manner as with + the "default" parameter, above. + + Important note: if your regular expression contains backslashes (by + themselves, or as part of an escaped character or symbol like \n or \W + ), you need to tell the parser that this expression must be parsed + "raw" by prepending the string with an "r": +locals = ( + (r'jeff\?\?\?@.', '[jeff]'), + ('alice@', '[alice]') + ) + +locals = ( + ('jeff@.', '[jeff]'), + (r'alice\D+@', '[alice]') + ) + + Note that if you don't understand regular expressions, you don't need + to worry about it. In general, an email address is a regular expression + that matches itself. The only significant times this isn't the case is + when the address contains odd punctuation characters like ^, $, \, or + [. Handy hints: + * the regular expression . (dot) matches anything + * matches can occur anywhere in the address. If you want to only + match at the beginning, start your expression with the ^ character. + If you only want to match the whole address, also end your + expression with a dollar sign $. + + Using regular expressions: + * The regular expression joe@example.org matches the addresses + joe@example.org, joe@example.org.net, and heyjoe@example.org. + * The regular expression ^jeff@ matches the addresses + jeff@example.org and jeff@example.net, but not + otherjeff@example.org. + * The regular expression sam matches the addresses sam@example.org, + samantha@example.org, asam@example.org, and chris@isam.example.net. + + Some examples: + * + + Deliver mail matching jeff@example.net to ~jeff/Maildir/ + + Deliver mail matching alice@anything to ~alice/inbox + + Deliver all other mail to ~bob/Maildir/ +[destination] +type = MultiSorter +default = [bob-default] +locals = ( + ('jeff@example.net', '[jeff]'), + ('alice@', '[alice]') + ) + +[jeff] +type = Maildir +path = ~jeff/Maildir/ +user = jeff + +[alice] +type = Mboxrd +path = ~alice/inbox +user = alice + +[bob-default] +type = Maildir +path = ~bob/Maildir/ +user = bob + + * + + Deliver mail for jeff, bob, and alice to maildirs in their + home directories + + Deliver copies of all messages to samantha's mail archive + + Deliver copies of all messages to a program that logs certain + information. This program should run as the user log, and + command arguments should tell it to record the info to + /var/log/mail/info +[destination] +type = MultiSorter +default = doesn't matter, this won't be used, as locals will always match +locals = ( + ('^jeff@', '[jeff]'), + ('^bob@', '[bob]'), + ('^alice@', '[alice]'), + ('.', '[copies]'), + ('.', '[info]') + ) + +[alice] +type = Maildir +path = ~alice/Maildir/ +user = alice + +[bob] +type = Maildir +path = ~bob/Maildir/ +user = bob + +[jeff] +type = Maildir +path = ~jeff/Maildir/ +user = jeff + +[copies] +type = Maildir +path = ~samantha/Mail/archive/copies/ +user = samantha + +[info] +type = MDA_external +path = /path/to/infologger +arguments = ('--log=/var/log/mail/info', '--sender=%(sender)', '--recipient=%(re +cipient)) +user = log + +MultiGuesser + + MultiGuesser tries to guess what the envelope recipient address of the + message might have been, by comparing addresses found in the message + header against a list of user-supplied regular expressions, and + delivers the message to the destination (maildir, mboxrd file, or + other) associated with any matching patterns. A message can match + multiple patterns and therefore be delivered to multiple matching + destinations. Any message which matches none of the patterns is + delivered to a default destination for the postmaster. In this fashion, + you can do basic mail filtering and sorting with getmail without using + an external filtering message delivery agent (MDA) (such as maildrop or + procmail), if and only if the message recipient is the criteria you + want to filter on. + + If you want to filter based on arbitrary message critera, like "What + address is in the To: header field?" or "Who is the message from?", + then use the filtering MDA of your choice, called from a getmail + MDA_external destination. + + MultiGuesser is similar to MultiSorter, except that it does not operate + on the true envelope recipient address, and therefore does not require + a domain mailbox retriever. Because it is "guessing" at the intended + recipient of the message based on the contents of the message header, + it is fallible — for instance, the address of a recipient of a mailing + list message may not appear in the header of the message at all. If + your locals regular expression patterns are only looking for that + address, MultiGuesser will then have to deliver it to the destination + specified as the default recipient. + + This functionality is very similar to the guessing functionality of + getmail version 2, which was removed in version 3. MultiGuesser + extracts a list of addresses from the message header like this: + 1. it looks for addresses in any Delivered-To: header fields. + 2. if no addresses have been found, it looks for addresses in any + Envelope-To: header fields. + 3. if no addresses have been found, it looks for addresses in any + X-Envelope-To: header fields. + 4. if no addresses have been found, it looks for addresses in any + Apparently-To: header fields. + 5. if no addresses have been found, it looks for addresses in any + Resent-to: or Resent-cc: header fields (or Resent-bcc:, which + shouldn't be present). + 6. if no addresses have been found, it looks for addresses in any To: + or cc: header fields (or bcc:, which shouldn't be present). + + The MultiGuesser destination takes one required parameter: + * default (string) — see MultiSorter for definition. + + The MultiGuesser destination also takes one optional parameter: + * locals (tuple of 2-tuples) — see MultiSorter for definition. + + Examples: + + If you have a simple POP3 account (i.e. it's not a multidrop mailbox) + and you want to deliver your personal mail to your regular maildir, but + deliver mail from a couple of mailing lists (identified by the list + address appearing in the message header) to separate maildirs, you + could use a MultiGuesser configuration like this: +[destination] +type = MultiGuesser +default = ~/Maildir/ +locals = ( + ("list-address-1@list-domain-1", "~/Mail/mailing-lists/list-1/"), + ("list-address-2@list-domain-2", "~/Mail/mailing-lists/list-2/"), + ) + + See MultiSorter above for other examples of getmail rc usage; the only + difference is the type parameter specifying the MultiGuesser + destination. + +MDA_qmaillocal + + MDA_qmaillocal delivers messages by running the qmail-local program as + an external MDA. qmail-local uses .qmail files to tell it what to do + with messages. If you're not already familiar with qmail, you don't + need to use this destination class. + + The MDA_qmaillocal destination takes several optional parameters: + * qmaillocal (string) — path to the qmail-local program. The default + value is /var/qmail/bin/qmail-local. + * user (string) — supplied to qmail-local, and also tells getmail to + change the current effective UID to that of the named user before + running qmail-local. Note that this typically requires root + privileges. The default value is the account name of the current + effective UID. + * group (string) — if supplied, getmail will change the effective GID + to that of the named group before running qmail-local. Note that + this typically requires root privileges. + * homedir (string) — supplied to qmail-local. The default value is + the home directory of the account with the current effective UID. + * localdomain (string) — supplied to qmail-local as its domain + argument. The default value is the fully-qualified domain name of + the local host. + * defaultdelivery (string) — supplied to qmail-local as its + defaultdelivery argument. The default value is ./Maildir/. + * conf-break (string) — supplied to qmail-local as its dash argument. + The default value is -. + * localpart_translate (2-tuple of quoted strings) — if supplied, the + recipient address of the message (which is used to construct the + local argument (among others) to qmail-local) will have any leading + instance of the first string replaced with the second string. This + can be used to remap recipient addresses, trim extraneous prefixes + (such as the qmail virtualdomain prepend value), or perform other + tasks. The default value is ('', '') (i.e., no translation). + * strip_delivered_to (boolean) — if set, Delivered-To: header fields + will be removed from the message before handing it to qmail-local. + This may be necessary to prevent qmail-local falsely detecting a + looping message if (for instance) the system retrieving messages + otherwise believes it has the same domain name as the retrieval + server. Inappropriate use of this option may cause message loops. + The default value is False. + * allow_root_commands (boolean) — if set, getmail will run + qmail-local even if it is currently running with root privileges. + The default is false, which causes getmail to raise an exception if + it is asked to run an external command as root. Note that setting + this option has serious security implications. Don't use it if you + don't know what you're doing. I strongly recommend against running + external processes as root. + + A basic invocation of qmail-local might look like this: +[destination] +type = MDA_qmaillocal +user = joyce + + Something more complex might look like this: +[destination] +type = MDA_qmaillocal +user = joyce +# The mail domain isn't the normal FQDN of the server running getmail +localdomain = host.example.net +# Trim the server's virtualdomain prepend value from message recipient before +# sending it to qmail-local +localpart_translate = ('mailhostaccount-', '') + +Creating the [options] section + + The optional options section of the rc file can be used to alter + getmail's default behaviour. The parameters supported in this section + are as follows: + * verbose (integer) — controls getmail's verbosity. If set to 2, + getmail prints messages about each of its actions. If set to 1, it + prints messages about retrieving and deleting messages (only). If + set to 0, getmail will only print warnings and errors. Default: 1. + * read_all (boolean) — if set, getmail retrieves all available + messages. If unset, getmail only retrieves messages it has not seen + before. Default: True. + * delete (boolean) — if set, getmail will delete messages after + retrieving and successfully delivering them. If unset, getmail will + leave messages on the server after retrieving them. Default: False. + * delete_after (integer) — if set, getmail will delete messages this + number of days after first seeing them, if they have been retrieved + and delivered. This, in effect, leaves messages on the server for a + configurable number of days after retrieving them. Note that the + delete parameter has higher priority; if both are set, the messages + will be deleted immediately. Default: 0, which means not to enable + this feature. + * delete_bigger_than (integer) — if set, getmail will delete messages + larger than this number of bytes after retrieving them, even if the + delete and delete_after options are disabled. The purpose of this + feature is to allow deleting only large messages, to help keep a + mailbox under quota. Has no effect if delete is set, as that will + unconditionally remove messages. If delete_after is also set, the + message will be deleted immediately after retrieval if it is over + this size, and otherwise will be deleted according to the setting + of delete_after. Default: 0, which means not to enable this + feature. + * max_bytes_per_session (integer) — if set, getmail will retrieve + messages totalling up to this number of bytes before closing the + session with the server. This can be useful if you do not want + large messages causing large bursts of network traffic. Default: 0, + which means not to enable this feature. Note that message sizes + reported by the server are used, and therefore may vary slightly + from the actual size on disk after message retrieval. + * max_message_size (integer) — if set, getmail will not retrieve + messages larger than this number of bytes. Default: 0, which means + not to enable this feature. + * max_messages_per_session (integer) — if set, getmail will process a + maximum of this number of messages before closing the session with + the server. This can be useful if your network or the server is + particuarly unreliable. Default: 0, which means not to enable this + feature. + * delivered_to (boolean) — if set, getmail adds a Delivered-To: + header field to the message. If unset, it will not do so. Default: + True. Note that this field will contain the envelope recipient of + the message if the retriever in use is a multidrop retriever; + otherwise it will contain the string "unknown". + * received (boolean) — if set, getmail adds a Received: header field + to the message. If unset, it will not do so. Default: True. + * message_log (string) — if set, getmail will record a log of its + actions to the named file. The value will be expanded for leading ~ + or ~USER and environment variables in the form $VARNAME or + ${VARNAME}. Default: '' (the empty string), which means not to + enable this feature. + * message_log_syslog (boolean) — if set, getmail will record a log of + its actions using the system logger. Note that syslog is inherently + unreliable and can lose log messages. Default: False. + * message_log_verbose (boolean) — if set, getmail will log to the + message log file (or syslog) information about messages not + retrieved and the reason for not retrieving them, as well as + starting and ending information lines. By default, it will log only + about messages actually retrieved, and about error conditions. Note + that this has no effect if neither message_log nor + message_log_syslog is in use. Default: False. + + Most users will want to either enable the delete option (to delete mail + after retrieving it), or disable the read_all option (to only retrieve + previously-unread mail). + + The verbose, read_all, and delete parameters can be overridden at run + time with commandline options. + +[options] example + + To configure getmail to operate quietly, to retrieve only new mail, to + delete messages after retrieving them, and to log its actions to a + file, you could provide the following in your getmail rc file(s): +[options] +verbose = 0 +read_all = false +delete = true +message_log = ~/.getmail/log + +Creating the [filter-something] sections + + The filter-something section(s) of the rc file (which are not required) + tell getmail to process messages in some way after retrieving them, but + before delivering them to your destinations. Filters can tell getmail + to drop a message (i.e. not deliver it at all), add information to the + message header (i.e. for a spam- classification system or similar), or + modify message content (like an antivirus system stripping suspected + MIME parts from messages). + + You can specify any number of filters; provide a separate rc file + section for each, naming each of them filter-something. They will be + run in collated order, so it's likely simplest to name them like this: + * [filter-1] + * [filter-2] + * [filter-3] + + Begin with the section header line as follows: +[filter-something] + + Then, include a type string parameter to tell getmail what type of + filter. The possible values are: + * Filter_classifier — run the message through an external program, + and insert the output of the program into + X-getmail-filter-classifier: header fields in the message. Messages + can be dropped by having the filter return specific exit codes. + * Filter_external — supply the message to an external program, which + can then modify the message in any fashion. The program must print + the modified message to stdout. getmail reads the modified message + from the program in this fasion before proceeding to the next + filter or destination. Messages can be dropped by having the filter + return specific exit codes. + * Filter_TMDA — run the message through the tmda-filter program for + use with the Tagged Message Delivery Agent (TMDA) package. If + tmda-filter returns 0, the message will be passed to the next + filter (or destination). If it returns 99, the message will be + dropped, and TMDA is responsible for sending a challenge message, + queuing the original, etc., as with normal TMDA operation in a + .qmail, .courier, or .forward file. + + By default, if a filter writes anything to stderr, getmail will + consider the delivery to have encountered an error. getmail will leave + the message on the server and proceed to the next message. You must + configure any filter you use not to emit messages to stderr except on + errors — please see the documentation for your filter program for + details. Optionally, if you know your filter can emit warnings on + stderr under non-error conditions, you can set the ignore_stderr + option. + +Filter_classifier + + Filter_classifier runs the message through an external program, placing + the output of that program into X-getmail-filter-classifier: header + fields. It can also cause messages to be dropped by exiting with a + return code listed in the exitcodes_drop parameter. + + Filter_classifier has one required parameter: + * path (string) — the path to the command to run. This value will be + expanded for leading ~ or ~USER and environment variables in the + form $VARNAME or ${VARNAME}. + + In addition, Filter_classifier takes the following optional parameters: + * arguments (tuple of quoted strings) — arguments to be supplied to + the command. The following substrings will be substituted with the + equivalent values from the message: + + %(sender) — envelope return-path address + If the message is retrieved with a multidrop retriever class, the + message recipient (and parts of it) are also available with the + following replacement substrings: + + %(recipient) — envelope recipient address + + %(local) — local-part of the envelope recipient address + + %(domain) — domain-part of the envelope recipient address + The default value of the arguments parameter is (), so no arguments + are supplied to the command. + * unixfrom (boolean) — whether to include a Unix-style mbox From_ + line at the beginning of the message supplied to the command. + Default: False. + * user (string) — if supplied, getmail will change the effective UID + to that of the named user. Note that this typically requires root + privileges. + * group (string) — if supplied, getmail will change the effective GID + to that of the named group. Note that this typically requires root + privileges. + * allow_root_commands (boolean) — if set, getmail will run external + commands even if it is currently running with root privileges. The + default is false, which causes getmail to raise an exception if it + is asked to run an external command as root. Note that setting this + option has serious security implications. Don't use it if you don't + know what you're doing. I strongly recommend against running + external processes as root. + * ignore_stderr (boolean) — if set, getmail will not consider it an + error if the filter writes to stderr. The default is false, which + causes getmail to consider the delivery failed and leave the + message on the server, proceeding to the next message. This + prevents loss of mail if the filter writes to stderr but fails to + exit nonzero when it encounters an error. Note that setting this + option has serious implications; some poorly-written programs + commonly used as mail filters can can mangle or drop mail but still + exit 0, their only clue to failure being warnings emitted on + stderr. Only change this setting if you are confident your filter + always exits nonzero on error. + * exitcodes_drop (tuple of integers) — if the filter returns an exit + code in this list, the message will be dropped. The default is (99, + 100). + * exitcodes_keep (tuple of integers) — if the filter returns an exit + code other than those in exitcodes_drop and exitcodes_keep, getmail + assumes the filter encountered an error. getmail will then not + proceed, so that the message is not lost. The default is (0, ). + +Filter_external + + Filter_external runs the message through an external program, and + replaces the message with the output of that program, allowing the + filter to make arbitrary changes to messages. It can also cause + messages to be dropped by exiting with a return code listed in the + exitcodes_drop parameter. + + Filter_external has one required parameter: + * path (string) — see Filter_classifier for definition. + + In addition, Filter_external takes the following optional parameters: + * arguments (tuple of quoted strings) — see Filter_classifier for + definition. + * unixfrom (boolean) — see Filter_classifier for definition. + * user (string) — see Filter_classifier for definition. + * group (string) — see Filter_classifier for definition. + * allow_root_commands (boolean) — see Filter_classifier for + definition. + * ignore_stderr (boolean) — see Filter_classifier for definition. + * exitcodes_drop (tuple of integers) — see Filter_classifier for + definition. + * exitcodes_keep (tuple of integers) — see Filter_classifier for + definition. + +Filter_TMDA + + Filter_external runs the message through the external program + tmda-filter, allowing the use of the Tagged Message Delivery Agent + (TMDA) package. As TMDA relies on the message envelope, this filter + requires the use of a multidrop retriever class to function. It sets + the three environment variables SENDER, RECIPIENT, and EXT prior to + running tmda-filter. + + I've tested this filter, and it Works For Me™, but I'm not a regular + TMDA user. I would appreciate any feedback about its use from TMDA + users. + + Filter_TMDA has no required parameters. It has the following optional + parameters: + * path (string) — the path to the tmda-filter binary. Default: + /usr/local/bin/tmda-filter. This value will be expanded for leading + ~ or ~USER and environment variables in the form $VARNAME or + ${VARNAME}. + * user (string) — see Filter_classifier for definition. + * group (string) — see Filter_classifier for definition. + * allow_root_commands (boolean) — see Filter_classifier for + definition. + * ignore_stderr (boolean) — see Filter_classifier for definition. + * conf-break (string) — this value will be used to split the + local-part of the envelope recipient address to determine the value + of the EXT environment variable. For example, if the envelope + sender address is sender-something@host.example.org, and the + envelope recipient address is user-ext-ext2@host.example.net, and + conf-break is set to -, getmail will set the environment variables + SENDER to "sender-something@host.example.org", RECIPIENT to + "user-ext-ext2@host.example.net", and EXT to "ext-ext2". Default: + "-". + +[filter-something] examples + + You might filter spam messages in your MUA based on information added + to the message header by a spam-classification program. You could have + that information added to the message header with a filter + configuration like this: +[filter-3] +type = Filter_classifier +path = /path/to/my-classifier +arguments = ('--message-from-stdin', '--report-to-stdout') +user = nobody + + You might use a program to prevent users from accidentally destroying + their data by stripping suspected attachments from messages. You could + have that information added to the message header with a filter + configuration like this: +[filter-3] +type = Filter_external +path = /path/to/my-mime-filter +arguments = ('--message-from-stdin', '--remove-all-but-attachment-types=text/pla +in,text/rfc822') +user = nobody + + You might use TMDA to challenge messages from unknown senders. If the + default parameters are fine for your configuration, this is as simple + as: +[filter-3] +type = Filter_TMDA + +getmail rc file examples + + Several examples of different getmail rc configuration are available in + the included file getmailrc-examples. + +Running getmail + + To use getmail, simply run the script getmail, which is typically + installed in /usr/local/bin/ by default. getmail will read the default + getmail rc file (getmailrc) from the default configuration/data + directory (~/.getmail/) and begin operating. + + You can modify this behaviour by supplying commandline options to + getmail. + +Commandline options + + getmail understands the following options: + * --version — show getmail's version number and exit + * --help or -h — show a brief usage summary and exit + * --getmaildir=DIR or -gDIR — use DIR for configuration and data + files + * --rcfile=FILE or -rFILE — read getmail rc file FILE instead of the + default. The file path is assumed to be relative to the getmaildir + directory unless this value starts with a slash (/). This option + can be given multiple times to have getmail retrieve mail from + multiple accounts. + * --dump — read rc files, dump configuration, and exit (debugging) + * --trace — print extended debugging information + + If you are using a single getmailrc file with an IMAP server that + understands the IDLE extension from RFC 2177, you can use the + --idle=MAILBOX option to specify that getmail should wait on the server + to notify getmail of new mail in the specified mailbox after getmail is + finished retrieving mail. + + In addition, the following commandline options can be used to override + any values specified in the [options] section of the getmail rc files: + * --verbose or -v — operate more verbosely. Can be given multiple + times. + * --quiet or -q — print only warnings or errors while running + * --delete or -d — delete messages after retrieving + * --dont-delete or -l — do not delete messages after retrieving + * --all or -a — retrieve all messages + * --new or -n — retrieve only new (unseen) messages + + For instance, if you want to retrieve mail from two different mail + accounts, create a getmail rc file for each of them (named, say, + getmailrc-account1 and getmailrc-account2) and put them in ~/.getmail/ + . Then run getmail as follows: +$ getmail --rcfile getmailrc-account1 --rcfile getmailrc-account2 + + If those files were located in a directory other than the default, and + you wanted to use that directory for storing the data files as well, + you could run getmail as follows: +$ getmail --getmaildir /path/to/otherdir --rcfile getmailrc-account1 --rcfile ge +tmailrc-account2 + +Using getmail as an MDA + + getmail includes helper scripts which allow you to use it to deliver + mail from other programs to maildirs or mboxrd files. + +Using the getmail_maildir MDA + + The getmail_maildir script can be used as an MDA from other programs to + deliver mail to maildirs. It reads the mail message from stdin, and + delivers it to a maildir path provided as an argument on the + commandline. This path must (after expansion by the shell, if + applicable) start with a dot or slash and end with a slash. + + getmail_maildir uses the contents of the SENDER environment variable to + construct a Return-Path: header field and the contents of the RECIPIENT + environment variable to construct a Delivered-To: header field at the + top of the message. + + getmail_maildir also accepts the options --verbose or -v which tell it + to print a status message on success. The default is to operate + silently unless an error occurs. + +Example + + You could deliver a message to a maildir named Maildir located in your + home directory by running the following command with the message on + stdin: +$ getmail_maildir $HOME/Maildir/ + +Using the getmail_mbox MDA + + The getmail_mbox script can be used as an MDA from other programs to + deliver mail to mboxrd-format mbox files. It reads the mail message + from stdin, and delivers it to an mbox path provided as an argument on + the commandline. This path must (after expansion by the shell, if + applicable) start with a dot or slash and not end with a slash. + + getmail_maildir uses the contents of the SENDER environment variable to + construct a Return-Path: header field and mbox From_ line and the + contents of the RECIPIENT environment variable to construct a + Delivered-To: header field at the top of the message. + + getmail_mbox also accepts the options --verbose or -v which tell it to + print a status message on success. The default is to operate silently + unless an error occurs. + +Example + + You could deliver a message to an mboxrd-format mbox file named inbox + located in a directory named mail in your home directory by running the + following command with the message on stdin: +$ getmail_mbox $HOME/mail/inbox + +Using getmail_fetch to retrieve mail from scripts + + getmail includes the getmail_fetch helper script, which allows you to + retrieve mail from a POP3 server without the use of a configuration + file. It is primarily intended for use in automated or scripted + environments, but can be used to retrieve mail normally. + + See the getmail_fetch manual page for details on the use of + getmail_fetch.
[-] [+]	Added	getmail-4.46.0.tar.bz2/docs/documentation.txt ^
@@ -0,0 +1,469 @@ +getmail documentation + + This is the documentation for getmail version 4. Version 4 includes + numerous changes from version 3.x; if you are using getmail version 3, + please refer to the documentation included with that version of the + software. + + getmail is Copyright © 1998-2009 Charles Cazabon. <charlesc-getmail @ + pyropus.ca> + + getmail is licensed under the GNU General Public License version 2 + (only). If you wish to obtain a license to distribute getmail under + other terms, please contact me directly. + +Table of Contents + + * getmail documentation + * + + getmail documentation + + + o Features + o Differences from previous versions + o Requirements + o Obtaining getmail + o Installing getmail + o + # For the impatient + # Full installation instructions + # Installing from the RPM + # Installing directly from the source + # + @ Installing in the default location + @ Installing under an alternate prefix directory + @ Installing parts of the package to alternate + directories + # Installing the getmailcore package in a non-standard + location + # Building a binary package from the source + o getmail mailing lists + o + # getmail-users' mailing list + # + @ How to subscribe + @ How to unsubscribe + @ How to post + @ Archives of the getmail-users' mailing list + @ Notes on the getmail-users' mailing list + # Announcements List + # + @ How to subscribe + @ How to unsubscribe + @ How to post + @ Archives of the getmail announcements mailing + list + * getmail configuration + * + + Configuring getmail + + + o Creating a getmail rc file + + Running getmail + + + o Commandline options + o Using getmail as an MDA + o Using getmail_fetch to retrieve mail from scripts + * getmail troubleshooting + * + + Troubleshooting problems + + + o Error messages + o Warning messages + o Unexpected Behaviour + * getmail frequently-asked questions (FAQs) + * + + Frequently-Asked Questions (FAQs) + + + o About getmail + o Configuring getmail + o How do I … + o Using getmail with other software + o I think I found this bug in getmail … + +Features + + getmail is a mail retriever designed to allow you to get your mail from + one or more mail accounts on various mail servers to your local machine + for reading with a minimum of fuss. getmail is designed to be secure, + flexible, reliable, and easy-to-use. getmail is designed to replace + other mail retrievers such as fetchmail. + + getmail version 4 includes the following features: + * simple to install, configure, and use + * retrieve virtually any mail + + support for accessing mailboxes with the following protocols: + o POP3 + o POP3-over-SSL + o IMAP4 + o IMAP4-over-SSL + o SDPS (Demon UK's extensions to POP3) + + support for single-user and domain mailboxes + + retrieve mail from an unlimited number of mailboxes and + servers + + can remember which mail it has already retrieved, and can be + set to only download new messages + * support for message filtering, classification, and annotation by + external programs like spam filters and anti-virus programs + * support for delivering messages to different destinations based on + the message recipient + * reliability + + native safe and reliable delivery support for maildirs and + mboxrd files, in addition to delivery through arbitrary + external message delivery agents (MDAs) + + does not destroy information by rewriting mail headers + + does not cause mail loops by doing SMTP injection, and + therefore does not require that you run an MTA (like qmail or + sendmail) on your host + * written in Python, and therefore easy to extend or customize + + a flexible, extensible architecture so that support for new + mail access protocols, message filtering operations, or + destination types can be easily added + + cross-platform operation; getmail 4 should work on Unix/Linux, + Macintosh, and other platforms. Windows support available + under the free Cygwin package. + * winner of various software awards, including DaveCentral's "Best of + Linux" + +Differences from previous versions + + getmail version 4 has been completely rewritten. It is designed to + closely mimic the interface and user experience of getmail version 3, + but the new architecture necessitates some differences you will notice: + * the getmail rc file (configuration file) format has changed. If you + are upgrading from version 3, you will need to write a new + configuration file based on the contents of your old one. The new + file format resembles the old in many ways. Each account you + retrieve mail from will require a separate rc file, but getmail can + operate with multiple rc files simultaneously if you wish to + retrieve mail from multiple accounts. + * support for protocols other than POP3/SDPS. IMAP support is now + included, and other protocols can be added with relative ease. + * support for SSL-encrypted protocols. The included POP3 and IMAP + retriever classes are complemented by SSL-enabled counterparts. + * messages can be filtered or annotated by external programs like + spam filters and anti-Microsoft-worm programs. Filters can cause + messages to be dropped completely. + * a flexible, extensible architecture. Additional classes for + handling new mail protocols, filter types, or destination + mailstores can be added without needing to modify the main script + at all. Feel free to contact me if you need a custom retriever, + filter, or destination class written, or if you want commercial + support for getmail. + +Requirements + + getmail version 4 requires Python version 2.3.3 or later. If you have + only an earlier version of Python available, you can install the latest + version without disturbing your current version, or use getmail version + 3, which requires only Python version 1.5.2 or later. + + At the time of this writing, the current stable version of Python is + 2.3.4. You can download that version from the page at + http://www.python.org/2.3.4/ . Binary packages are available for + RPM-based Linux systems, or building Python from source is typically as + easy as unpacking the source tarball, and running the following + commands: +./configure +make +make install + + Since the above was written, Python 2.4 has been released. getmail 4 + will work with that version of Python as well. + + getmail 4 also requires that servers uniquely identify the messages + they provide (via the UIDL command) to getmail for full functionality. + Certain very old or broken POP3 servers may not be capable of this (I + have had only one report of such problems from among the tens of + thousands of people who have downloaded getmail 4 from my website and + from other archives), or may not implement the UIDL command at all, and + limited support is available for such servers via the + BrokenUIDLPOP3Retriever and BrokenUIDLPOP3SSLRetriever retriever + classes. + +Obtaining getmail + + Download getmail 4 from the official website main page at + http://pyropus.ca/software/getmail/ . + +Installing getmail + +For the impatient + + Installing getmail is very easy; just download the tarball + distribution, unpack it, change into the directory it unpacks into, and + run this command: +$ python setup.py install + + That's all there is to it. 99.9% of users don't need a special + package/port/etc. If you'd like more details on install options, keep + reading. + +Full installation instructions + + Once you have downloaded or otherwise obtained getmail, unpack it. On + GNU-ish Unix-like systems, this means: +$ tar xzf getmail-version.tar.gz + + On Macintosh systems, use a Zip-type archiver program to unpack the + tarball. + + On SystemV-like Unix systems, you may instead need to break this down + into two steps: +$ gunzip getmail-version.tar.gz +$ tar xf getmail-version.tar + + Then, change into the extracted getmail directory and start the build + process. The easiest installation method is to use the included + setup.py Python distutils script to build and install getmail directly. + Alternatively, you can build a binary package (i.e., an RPM or similar + managed software package) for your system from the source package and + install the resulting package, but the Python distutils support for + this is spotty at present. + +Installing from the RPM + + If you downloaded the RPM, you should be able to install it with the + following command: +$ rpm -ihv getmail-version-release.noarch.rpm + +Installing directly from the source + + To build and install directly from the included source, follow these + steps. +$ cd getmail-version +$ python setup.py build + + When that completes in a few seconds, become root and then install the + software. You can install in the default location, or specify an + alternate location to install the software, or specify alternate + directories for only part of the package. + +Installing in the default location + + To install in the default location, become user root and install with + the following commands: +$ su +enter root password +# python setup.py install + + This will, by default, install files into subdirectories under the + directory prefix, which is the directory that your Python installation + was configured to install under (typically /usr/local/ or /usr/, but + other values are sometimes used): + * the scripts getmail, getmail_fetch, getmail_maildir, and + getmail_mbox will be installed under prefix/bin/ + * the Python package getmailcore (which implements all the protocol–, + filter–, and destination-specific code for getmail, plus various + other bits) will be installed under the site-specific packages + directory of your Python library directory. This directory is + prefix/lib/python-python-version/site-packages/. + * The documentation directory getmail-getmail-version will be + installed under prefix/doc/ + * The manual pages for the four scripts will be installed under + prefix/man/ + + You can see a list of the default installation locations by running: +# python setup.py install --show-default-install-dirs + +Installing under an alternate prefix directory + + You can specify an alternate prefix directory by supplying the --prefix + option to the install command, like this: +# python setup.py install --prefix=path + + This will install the various parts of the package in subdirectories + like in the default installation (see the section Installing in the + default location above), but under your specified prefix directory. + These alternate installations allow you to install the software without + root privileges (say, by installing under $HOME/). Note, however, that + the getmailcore package will not be in the default Python module search + path if you do this; see the section Installing the getmailcore package + in a non-standard location if you use this option. + +Installing parts of the package to alternate directories + + If you only want to change the directory for some of the components, + use the following options: + * --install-lib=path specifies the directory the getmailcore package + is installed under (i.e., it will be installed as path/getmailcore + ). See the section Installing the getmailcore package in a + non-standard location if you use this option. + * --install-scripts=path specifies the directory the four scripts are + installed under (i.e., they will be installed directly in path/ ). + * --install-data=path specifies the directory the documentation is + installed under (i.e., the HTML and plaintext documentation will be + installed in the directory path/doc/getmail-getmail-version/, and + the man(1) pages will be installed in path/man/man1/. + + For example, if your Python installation is located under /usr/ because + it was installed as part of your OS, but you would like the getmail + scripts installed into /usr/local/bin/ instead of /usr/bin/, while + still letting the getmailcore package be installed under + /usr/lib/python-python-version/site-packages/, and the documentation + and man pages under /usr/doc/ and /usr/man/ you could use this command + to install: +# python setup.py --install-scripts=/usr/local/bin/ + + If you also wanted to locate the documentation and man pages under + /usr/local/ but still install the getmailcore package in the default + /usr/lib/python-python-version/site-packages/, you would instead use + this command to install: +# python setup.py --install-scripts=/usr/local/bin/ --install-data=/usr/local/ + +Installing the getmailcore package in a non-standard location + + Note: if you use one of the above methods to install the getmailcore + package into a directory other than the default, the four scripts + (getmail, getmail_fetch, getmail_maildir, and getmail_mbox) will almost + certainly be unable to locate the required files from the getmailcore + package, because they will not be in a directory in the standard Python + module search path. You will need to do one of the following to make + those files available to the scripts: + * set the environment variable PYTHONPATH to tell Python where to + find the appropriate modules. See the documentation at the + Python.org website for details. + Note that setting PYTHONPATH in $HOME/.profile (or equivalent) is + not sufficient -- for instance, cron runs jobs in a simpler + environment, ignoring $HOME/.profile, and getmail would therefore + fail when run as a user cron job. It is strongly recommended that + you install the Python library files in the site-packages directory + which Python provides for exactly this reason. + * modify the scripts to explicitly tell Python where you've installed + them. Insert a line like this: +sys.path.append('/path/to/installation-directory') + + containing the path to the directory you installed the getmailcore + directory in, somewhere below the line which reads +import sys + + and before the first line which references getmailcore . + +Building a binary package from the source + + To build a binary package from the included source, run the following + command from inside the unpacked getmail source. +$ cd getmail-version +$ python setup.py bdist --format=package-format + + The useful allowed values for package-format are: + * rpm — build a .noarch.rpm file which can then be installed with the + rpm package manager. + * pkgtool — build a package for the Sun Solaris pkgtool package + manager. + * sdux — build a package for the HP/UX swinstall software installer. + + Ideally, if you use this method, it will result in a "built + distribution" binary package in a subdirectory named dist which can + then be installed using the appropriate system-specific tool. If you + have problems with this process, please do not ask me for assistance; + ask your OS vendor or the comp.lang.python newsgroup. The + install-directory-from-source process above is the only one I can + support, and it should work on all platforms. + + You can discuss issues with building binary packages on the getmail + users' mailing list. + +getmail mailing lists + +getmail-users' mailing list + + A mailing list has been set up to discuss getmail. Only subscribers may + post to the list. + + The list is available for free getmail support from me and other users, + for discussions of bugs, configuration issues, documentation, and other + technical issues related to getmail. + +How to subscribe + + To subscribe to the list, send a blank email to <getmail-subscribe @ + lists.pyropus.ca> and follow the instructions in the message you + receive. Read and save the "welcome" message you receive when you + subscribe; it contains valuable instructions about how to use the list. + +How to unsubscribe + + To un-subscribe from the list, send a blank email from the same address + you subscribed with to <getmail-unsubscribe @ lists.pyropus.ca> and + follow the instructions in the message you receive. + +How to post + + Once you have subscribed to the list, you may post messages to the list + by sending them to <getmail @ lists.pyropus.ca>. Complete instructions + for using the list are sent to you when you subscribe. + + The list allows plaintext message bodies and plaintext attachments. Do + not attempt to send binary files (gzip, etc), HTML, or other types, as + they will be stripped from your message. + + Note: please ensure you have read the documentation and Frequently + Asked Questions, and browsed/searched the mailing list archives before + posting a question to the mailing list. + +Archives of the getmail-users' mailing list + + There are browsable archives of the list at + http://marc.theaimsgroup.com/?l=getmail&r=1&w=2 and + http://news.gmane.org/gmane.mail.getmail.user . The GMANE getmail + users' archive is also available via NNTP if you prefer to read it with + a newsreader, rather than a web browser. + +Notes on the getmail-users' mailing list + + When subscribing to the getmail users' mailing list, please note the + following: + * The mailing list software does not, and will not munge the + Reply-To: header of list messages. I encourage you to read and post + to the list using a good MUA that properly supports reply-to-list + and reply-to-author functionality. If your MUA lacks a + reply-to-list function, you'll need to manually ensure your + followup messages to the the list are actually directed to the list + submission address. + * The mailing list software does not munge the Subject: header of + list messages, so don't look for "[getmail-users]" or anything like + that. If you want your MUA to recognize list messages, there are a + number of header fields added to allow it to do so. + * Subscribing and unsubscribing from the list are both secure and + completely automatic. When you try to do either, the list manager + software will send you a special message you have to reply to to + finish the operation; this prevents others from subscribing you to + or unsubscribing you from the list without your permission. + * You must be a list subscriber to post messages to the list. + +Announcements List + + If you only want to be notified of new releases of getmail, an + announce-only list has been set up. The list is very low-volume; you + can expect to receive only a small number of messages per month. + + All announcements are sent to both lists, so there is no need to + subscribe to the announcements list if you are on the discussion list. + +How to subscribe + + To subscribe to the list, send a blank email to + <getmail-announce-subscribe @ lists.pyropus.ca> and follow the + instructions in the message you receive. Read and save the "welcome" + message you receive when you subscribe; it contains valuable + instructions about how to use the list. + +How to unsubscribe + + To un-subscribe from the list, send a blank email from the same address + you subscribed with to <getmail-announce-unsubscribe @ + lists.pyropus.ca> and follow the instructions in the message you + receive. + +How to post + + You cannot post messages directly to the announcements list. If you + feel you have an announcement regarding getmail which should be + distributed, send it to me and request that I send it to the + announcements list. + +Archives of the getmail announcements mailing list + + There is an archive of the announcements list at + http://news.gmane.org/gmane.mail.getmail.announce . The GMANE getmail + announcements archive is also available via NNTP if you prefer to read + it with a newsreader, rather than a web browser.
[-] [+]	Added	getmail-4.46.0.tar.bz2/docs/faq.txt ^
@@ -0,0 +1,1156 @@ +getmail documentation + + This is the documentation for getmail version 4. Version 4 includes + numerous changes from version 3.x; if you are using getmail version 3, + please refer to the documentation included with that version of the + software. + + getmail is Copyright © 1998-2009 Charles Cazabon. + + getmail is licensed under the GNU General Public License version 2 + (only). If you wish to obtain a license to distribute getmail under + other terms, please contact me directly. + +Table of Contents + + * getmail documentation + * + + getmail documentation + + + o Features + o Differences from previous versions + o Requirements + o Obtaining getmail + o Installing getmail + o getmail mailing lists + * getmail configuration + * + + Configuring getmail + + + o Creating a getmail rc file + + Running getmail + + + o Commandline options + o Using getmail as an MDA + o Using getmail_fetch to retrieve mail from scripts + * getmail troubleshooting + * + + Troubleshooting problems + + + o Error messages + o Warning messages + o Unexpected Behaviour + * getmail frequently-asked questions (FAQs) + * + + Frequently-Asked Questions (FAQs) + + + o About getmail + o + # What is getmail? + # What platforms/machines does getmail run on? + # + @ Does getmail run on MS Windows? + @ Does getmail run on Macintosh systems? + @ Does getmail require Unix/Linux? + # How can I get support for getmail? + # I think I found a bug! How do I report it? + # I have a neat idea for random feature "foo" … how do + I get you to implement it? + # Why won't you implement random feature "foo"? + # Does getmail support virus scanning of retrieved + messages? + # Does getmail support spam filtering of retrieved + messages? + # Does getmail support SSL? + # Does getmail rewrite mail headers when it retrieves + mail? + # Can I upgrade from getmail 3 to getmail 4? What + about my "oldmail" files? + # Why did you write getmail? Why not just use + fetchmail? + o Configuring getmail + o + # What is a "domain mailbox"? + # Do I have to run sendmail or another MTA to use + getmail? + # Will getmail deliver mail as root? + # What's a maildir? + # What's "mboxrd" format? + # What's this "envelope sender" and "envelope + recipient" stuff? + # + @ Message header vs. message envelope + @ Receiving messages without your address in the + message header + @ Responsibility for recording the message + envelope + @ How this relates to domain or multidrop + mailboxes + # This rc stuff seems complicated. Does it have to be? + o How do I … + o + # How do I retrieve mail from multiple accounts? + # How do I get getmail to deliver messages to + different mailboxes based on … + # How do I stop getmail adding a Delivered-To: header + to messages? + # How do I stop getmail adding a Received: header to + messages? + # How do I make getmail deliver messages by + re-injecting with SMTP? + # How do I create a maildir? + # How do I create an mboxrd file? + # How do I make getmail deliver messages to an mh + folder? + # How do I run getmail in "daemon" mode? + # How do I make getmail stop after retrieving X + messages so that the server actually flushes deleted + messages? + # How do I make getmail retrieve mail from Hotmail? + # I'm using getmail. How do I make it … + # + @ I'm running getmail from cron. How do I + temporarily stop it? + @ How do I stop multiple instances of getmail + from running at the same time? + o Using getmail with other software + o + # How do I use SpamAssassin with getmail? + # How do I use ClamAV with getmail? + # + @ Getting prettier output from ClamAV + # How do I use F-Prot with getmail? + # How do I use procmail with getmail? + # How do I use maildrop with getmail? + # How do I use TMDA with getmail? + # + @ How can I get Gmail labels with getmail? + o I think I found this bug in getmail … + o + # getmail doesn't download all my mail from Gmail … + # FutureWarning: %u/%o/%x/%X of negative int will + return a signed string in Python 2.4 and up + # AttributeError: 'module' object has no attribute + 'fsync' + # operation error (SimplePOP3Retriever: [...] does not + uniquely identify messages [...] see documentation + or use BrokenUIDLPOP3Retriever instead + # MemoryError on OS X + # MemoryError when using IMAP + +Frequently-Asked Questions (FAQs) + + The following questions about getmail are answered more-or-less + frequently. Please also read the unexpected behaviour section of the + troubleshooting document. + +About getmail + +What is getmail? + + getmail is a mail retriever with support for POP3, POP3-over-SSL, + IMAP4, IMAP4-over-SSL, and SDPS mail accounts. It supports normal + single-user mail accounts and multidrop (domain) mailboxes. getmail is + written in Python, and licensed under the GNU General Public License + version 2. + +What platforms/machines does getmail run on? + + getmail runs on basically any platform. It's designed to, and written + in a language that helps to maintain cross-platform compatibility. + getmail is known to run on the following platforms: + * Linux-based GNU systems (all distributions) + * HURD-based GNU systems + * FreeBSD + * OpenBSD + * NetBSD + * HP/UX + * Sun Solaris + * IBM AIX + * Digital/Compaq Tru64 (a.k.a OSF/1) UNIX + * SGI Irix + * other commercial Unices + * Digital VMS / OpenVMS + * BeOS + * Amiga OS + * OS/2 + * Cygwin on Windows + * Macintosh OS X + * Macintosh OS 9 + + But getmail will also run on other, less common platforms. The only + real requirement is that Python run on that platform, and porting + Python is generally very easy. + +Does getmail run on MS Windows? + + Yes, under the free Cygwin package. Running recent versions of Python + under Cygwin requires a process known as "rebasing" your Cygwin + installation; you can find details in this Python developers' mailing + list message. + +Does getmail run on Macintosh systems? + + Yes. + +Does getmail require Unix/Linux? + + No. + +How can I get support for getmail? + + getmail is Free Software. As such, it comes with no warranty. However, + I will do my best to support getmail on a voluntary basis through the + getmail mailing list. + + If you are using getmail in a commercial or other environment where + problems cost money, consider contacting me privately for commercial + support, by emailing <charlesc-getmail-support @ pyropus.ca> + + If you have questions about getmail, the first step is to read the + documentation, and the remainder of the Frequently Asked Questions. If + your question isn't answered there, search the getmail mailing list + archives. + + If you still haven't found an answer to your question, please subscribe + to the getmail users' mailing list by sending a blank email to + <getmail-subscribe @ lists.pyropus.ca>. If you post your question + there, I will see it. As an additional bonus, your question may be + answered by another member of the list. + +I think I found a bug! How do I report it? + + First, make sure that you are running the latest version. You can + always find what is the latest version by checking this page at the + original web site: + http://pyropus.ca/software/getmail/. + If you running an older version of the software, chances are whatever + bug you may have found has already been fixed. + + Ideally, you should join the mailing list and send your bug report + there. You should include the following information: + * getmail version + * Python version + * any error message which getmail displayed + * the output from running getmail with your normal options plus + --dump + * if your problem is getmail not determining the proper local + recipient, please include the output of running getmail with your + normal options plus --trace, showing the retrieval of one + problematic message. + + If you absolutely cannot sign up for the mailing list, send the report + to me directly at <charlesc-getmail-bugs @ pyropus.ca>. I may not be + able to respond to all reports privately, but I will try to address any + bugs I find out about this way. + +I have a neat idea for random feature "foo" … how do I get you to implement +it? + + Follow the same instructions as for reporting bugs above — yes, that + means I would prefer you submit your idea to the getmail users' mailing + list. That will lead to a useful discussion if your feature has not + been proposed before. + +Why won't you implement random feature "foo"? + + Every line of code added to getmail has a certain cost. Every feature + added requires code, documentation, and support. Adding features + increases the complexity of the software, confuses users, and leads to + higher support costs. I therefore weigh features very carefully as a + cost-versus-benefit tradeoff before deciding whether to add them. + + Some users are confused by this. They think that a feature you don't + use has no cost, and therefore if it has any value to anyone, it should + be added. That simply isn't the case; the costs of an unused feature + are simply borne by others, including me. + + If you have asked me to add some feature, and I've said no, this may be + the reason. Other possibilities include me simply not having had + sufficient time to implement it yet. + +Does getmail support virus scanning of retrieved messages? + + Yes. You can use getmail message filtering options to do this with an + external virus scanning program, or invoke your virus scanning program + during delivery with getmail's support for external MDAs. + + Also see the FAQ about using getmail with the ClamAV program. + +Does getmail support spam filtering of retrieved messages? + + Yes. You can use getmail message filtering options to do this with an + external spam filtering program, or invoke your spam filtering program + during delivery with getmail's support for external MDAs. + + Also see the FAQ about using getmail with the SpamAssassin program. + +Does getmail support SSL? + + Yes. getmail has built in support for POP3-over-SSL and IMAP4-over-SSL. + +Does getmail rewrite mail headers when it retrieves mail? + + No. Rewriting message header fields is bad for many reasons; the + biggest problem is that it causes a loss of critical technical + information necessary to track down many mail problems. getmail will + add a new Received: header field and a new Delivered-To: header field, + but does not rewrite existing headers. You can disable the creation of + these header fields. + +Can I upgrade from getmail 3 to getmail 4? What about my "oldmail" files? + + Yes. getmail version 4 uses exactly the same + oldmail-server-port-username naming convention for its oldmail files. + The only difference is that version 4 escapes a couple of additional + characters in this string so that it is truly cross-platform + compatible. If you upgrade from version 3 to version 4, getmail will + still remember which messages you've already retrieved. + + To upgrade, do the following: + 1. Rename your old getmail rc file, creating a new file in + ~/.getmail/getmailrc. + 2. Create a new [options] section, containing the appropriate values + from your version 3 rc file [defaults] section. + 3. Create a new [retriever] section, using your previous server + configuration values in a new type = SimplePOP3Retriever or type = + MultidropPOP3Retriever as appropriate. + 4. Create a new [destination] section, using your previous destination + path values in a new type = Maildir, type = Mboxrd, type = + MDA_external, or type = MultiSorter destination as appropriate. + 5. If you were retrieving messages from multiple mail accounts in a + single version 3 getmail rc file, split them up into one account + per version 4 rc file. + + That's it. + +Why did you write getmail? Why not just use fetchmail? + + Short answer: … well, the short answer is mostly unprintable. The long + answer is … well, long: + + I do not like some of the design choices which were made with + fetchmail. getmail does things a little differently, and for my + purposes, better. In addition, most people find getmail easier to + configure and use than fetchmail. Perhaps most importantly, getmail + goes to great lengths to ensure that mail is never lost, while + fetchmail (in its default configuration) frequently loses mail, causes + mail loops, bounces legitimate messages, and causes many other + problems. + + When people have pointed out problems in fetchmail's design and + implementation, it's maintainer has frequently ignored them, or (worse + yet) gone in the completely wrong direction in the name of "fixing" the + problems. For instance, fetchmail's configuration file syntax has been + criticized as being needlessly difficult to write; instead of cleaning + up the syntax, the maintainer instead included a GUI + configuration-file-writing program, leading to comments like: + + The punchline is that fetchmail sucks, even if it does have + giddily-engineered whizbang configurator apps. + + As an example, Dan Bernstein, author of qmail and other software + packages, once noted to the qmail list: + + Last night, root@xxxxxxxxxxxxxxxxx reinjected thirty old messages + from various authors to qmail@xxxxxxxxxxxxxx + + This sort of idiocy happens much more often than most subscribers + know, thanks to a broken piece of software by Eric Raymond called + fetchmail. Fortunately, qmail and ezmlm have loop-prevention + mechanisms that stop these messages before they are distributed to + subscribers. The messages end up bouncing to the wrong place, thanks + to another fetchmail bug, but at least the mailing list is + protected. + + --D. J. Bernstein + + The maintainer also ignored dozens of complaints about fetchmail's + behaviour, stating (by fiat) that fetchmail was bug-free and had + entered "maintenance mode", allowing him to ignore further bug reports. + + fetchmail's default configuration values frequently cause lost or + misdirected mail, and seem to be chosen to cause maximum pain and + inconvenience. From fetchmail's to-do file (emphasis mine): + + Maybe refuse multidrop configuration unless "envelope" is + _explicitly_ configured … This would prevent a significant class of + shoot-self-in-foot problems. + + perhaps treat a delivery as "temporarily failed" … This is so you + don't lose mail if you configure the wrong envelope header. + + fetchmail is famous for mangling messages it retrieves, rather than + leaving them alone as a mail-handling program should. getmail will add + trace information to messages (so you can see what happened, and when), + but will otherwise leave message content alone. + + In addition, fetchmail has a long history of security problems: + * versions released before 20 June 2001 contain a buffer overflow, + which can be remotely exploited (see www.securityfocus.com/bid/2877 + for details). getmail is not vulnerable to buffer overflows, + because buffers in Python are dynamically sized. + * Another remotely-exploitable security hole discovered in fetchmail + in June 2002; versions prior to 5.9.10 (released in June 2002) are + exploitable . + * Reading fetchmail's UPDATES file, it appears that another security + problem was fixed in 5.9.12, where a server could crash fetchmail + on 64-bit platforms. Also worrying is a mention that it includes a + fix for "password shrouding". + * Another remotely-exploitable security hole in fetchmail discovered + in September 2002; this hole lets an attacker run arbitrary code on + the victim's computer. + * Another remotely-exploitable security hole in fetchmail discovered + in December 2002; once again, a remote attacker can run arbitrary + code on the machine running fetchmail in its default configuration. + See this advisory for details. + * January 2003: More buffer overflows in fetchmail let attackers run + arbitrary code . + * October 2003: Anyone can cause fetchmail to crash by sending you a + message . Other problems are here , and I might have missed some . + * Just in case you thought fetchmail was all better now, there's + still new security problems being discovered in it. In December, + 2005, it was revealed that anyone can send a fetchmail multidrop + user a message that causes fetchmail to crash. + + In July, 2004, it was noted that there may be at least 2 unfixed + denial-of-service attacks, 2 unfixed remote-code-execution, 2 unfixed + remote-user-access, and 3 unfixed remote-shell attacks against + fetchmail. See + http://www.mail-archive.com/euglug@euglug.org/msg00971.html for details + + I've given up even trying to stay abreast of the various security holes + in fetchmail, but others have noted continuing problems, including: + * another arbitrary code execution vulnerability announced on 21 July + 2005. + + The fetchmail authors' boneheaded decision to create a + configuration-file GUI editor (rather than actually giving fetchmail a + sane configuration syntax) also came back to bite them in the ass: in + October 2005, it became known that fetchmailconf created its files in + such a way that users' passwords could be read during file creation. + + Addendum, January 2007: since I wrote the above, the following new + security problems have been discovered in fetchmail: + * CVE-2005-4348 - anyone can crash fetchmail by sending messages + without headers + * CVE-2006-0321 - anyone can crash fetchmail by sending a message + that fetchmail tries to bounce + * CVE-2006-5867 - fetchmail can transmit passwords in plaintext even + if the user has configured it not to + * CVE-2006-5974 - anyone can cause fetchmail to crash by triggering + certain error code paths + + But don't just take my word for it; see + http://docs.freebsd.org/cgi/mid.cgi?200102172349.QAA11724 and + http://esr.1accesshost.com/ (note: went offline sometime in 2009 or + 2010; the content is still available at + http://web.archive.org/web/20080621090439/http://esr.1accesshost.com/ + ). + + getmail users have not had to worry about any of these security holes + or design and implementation errors. + +Configuring getmail + +What is a "domain mailbox"? + + A domain (or multidrop) mailbox is a POP3 mailbox which receives mail + for all users in a given domain. Normal mailboxes contain mail for a + single user (like jason@myisp.co.uk); some Internet Service Providers + which provide webhosting or other services will provide a POP3 mailbox + which receives mail for all addresses in a given domain (i.e. mail for + service@smallcompany.net, sales@smallcompany.net, and indeed anything + @smallcompany.net ends up in the same POP3 mailbox). + + getmail provides a method of retrieving mail from a domain mailbox and + distributing it among the various users automatically. The retriever + classes MultidropPOP3Retriever, MultidropPOP3SSLRetriever, + MultidropSDPSRetriever, MultidropIMAPRetriever, and + MultidropIMAPSSLRetriever provide this capability. + + See the documentation on the [retriever] section for details of what + the requirements for a multidrop mailbox are. getmail user Matthias + Andree also has a web page about multidrop mailboxes. + +Do I have to run sendmail or another MTA to use getmail? + + No. getmail delivers directly to maildirs, mboxrd files, or via + arbitrary MDAs, and never injects mail via SMTP, so no MTA is + necessary. + +Will getmail deliver mail as root? + + No. When run as the root user on a Unix-like system, getmail drops + privileges (switches to an unprivileged group and user id) before + delivering to maildirs or mboxrd files. You can specify the user + explicitly, or let getmail use the owner of the maildir or mboxrd file. + + If getmail attempts to deliver mail and finds it has UID 0 or GID 0, it + will refuse the delivery and print an error message. + +What's a maildir? + + A maildir is a mail storage format invented by D. J. Bernstein (author + of qmail) that requires no file locking to deliver to safely and + reliably, even over NFS. getmail natively supports delivery to + maildirs. + + See http://qmail.org/man/man5/maildir.html and + http://cr.yp.to/proto/maildir.html for details. + +What's "mboxrd" format? + + There are various sub-types of the mbox mail storage format. mboxrd is + the most reliable of them, though (like all mbox types) it still relies + on file locking and is therefore more easily corrupted than maildir + format. In particular, using mbox files with multiple writers over NFS + can be problematic. + + For details on the differences between the various mbox sub-types, see + http://qmail.org/man/man5/mbox.html. + +What's this "envelope sender" and "envelope recipient" stuff? + + The "envelope" of an email message is "message metadata"; that is, the + message is information, and the envelope is information about the + message (information about other information). Knowing this is critical + to understanding what a domain or multidrop mailbox is, how it works, + and what getmail can do for you. + + Others have tried to explain this with varying degrees of success. I'll + use the standard analogy of normal postal (i.e. non-electronic) mail: + +Message header vs. message envelope + + When you receive a letter (a reply from the customer-disservice + department of your telephone company, say) it arrives in an envelope. + You tear it open, remove the letter, and read it. At the top of the + letter is the telephone company's return address, followed by the date + the letter was written. Your name and mailing address follow that, and + then the remainder of the letter. + + The important thing to keep in mind is that the contents of the letter + (including the addresses just discussed) are never looked at by the + post office. If they can't deliver the letter (your mailing address on + the envelope got smudged in the rain), they'll return it to the address + listed in the top-left corner of the envelope. They don't check to make + sure that the address listed there is the same as the one listed at the + top of the letter. Similarly, when they can successfully deliver it, + they don't check to make sure that the recipient name and address on + the envelope matches the one listed on the letter between the date and + the salutation. + + The message header fields From: and Resent-from: are equivalent to the + block of address information at the top of the letter; it usually + contains the name and address of the sender of the message, but it is + never actually used in the delivery of the message. Similarly, the To:, + cc:, Resent-to:, and Resent-cc: header fields are the equivalent of the + block of address information between the date and the salutation on the + letter; they usually contain the names and addresses of the intended + recipients of the message, but they too are not used in the delivery of + the message. + +Receiving messages without your address in the message header + + You might open an envelope addressed to you and find that the letter + inside makes no mention of your name. Your name and address don't + appear anywhere in the letter, but it was still successfully delivered + to you based on the envelope information. There's nothing strange about + this. If someone else opens your mail for you, discards the envelopes, + and places the contents in your in-basket, you might wonder how some of + it ended up there, because there's nothing to connect you with the + message contents. + + Email is exactly like this. Each message has two parts, the message + contents, and the message envelope. The message contents include the + message header, and the message body. The message envelope is made up + of exactly one envelope sender address (which can be empty) and one or + more envelope recipient addresses. If the message cannot be delivered + for any reason, and the envelope sender address is not empty, the + message must be returned to the envelope sender address by the mail + transfer agent (MTA) which last accepted responsibility for delivering + the message. These notifications are known as "bounce messages" or + sometimes as "non-delivery notifications". Bounce messages are sent + using the empty envelope return path, to prevent mail loops from + occurring when a bounce message itself cannot be delivered. + + Confusion often arises among novice users about the difference between + the message header and the message envelope; they seem to believe that + they are not independant. This appears to be an artifact of their use + of simple-minded GUI mail user agents (MUAs) that do not allow them to + set the envelopes of their messages explicitly, but instead simply use + the contents of the From: header field as the envelope sender address, + and any addresses found in To:, cc:, and bcc: header fields as the + envelope recipient addresses. While these are sensible as default + values, more powerful MUAs allow the user to override this choice. + +Responsibility for recording the message envelope + + The last MTA to receive a message (usually the one running on the POP + or IMAP server where you retrieve your mail from) essentially acts as + your correspondence secretary, accepting your mail from the postman, + opening it, and placing it into your in-basket. Note that this would + normally destroy the important information contained in the message + envelope. To prevent this loss of information, this MTA is supposed to + copy the information from the envelope into new fields in the header of + the message content, as if your secretrary copied the sender and + recipient addresses onto the back of your letters in felt pen. + Unfortunately, some MTAs do not always do this properly, and envelope + information can then be lost. When this happens, it makes dealing with + certain types of mail messages problematic: + * bcc'd messages (bcc stands for blind carbon copy), where you are an + envelope recipient, but your address does not appear in the message + content (i.e., your address does not appear in a To:, cc:, or + similar message header field). With bcc'd messages, the From: + header field contains the name and address of the author of the + message, and the To: and cc: header fields contain the names and + addresses of the other, non-blind recipients of the message. + * mailing list messages, where you are an envelope recipient, but + your address does not appear in the message content (i.e., your + address does not appear in a To:, cc:, or similar message header + field). Mailing list messages have the envelope sender address set + to the mailing list manager (so that it can monitor "bad" list + addresses for bounces), while the From: header field contains the + name and address of the author of the message. The envelope + recipient addresses of mailing list messages are the addresses of + the list subscribers, while the To: header field usually contains + the address of the mailing list. + * other, less common cases. + + MTAs are supposed to record the envelope sender address by placing it + into a new Return-Path: header field at the top of the message. They + should then record the envelope recipient address(es) in another new + header field; sometimes this header field is named Delivered-To:, but + it can also be Envelope-To: or one of a few other names. + +How this relates to domain or multidrop mailboxes + + A domain or multidrop mailbox is one which receives mail for multiple + email addresses (commonly all addresses in a given domain). If you do + not want all of this mail to go to one person, you need to know who the + messages were originally addressed to after retrieving them from the + POP/IMAP multidrop mailbox. You cannot do this by looking at the To:, + cc:, or other informational message header fields, because they do not + actually reflect the message envelope at the time of delivery. Instead, + you have to reconstruct the envelope information from the message + header fields which the MTA on the server used to record it at the time + of delivery. + + If the final MTA does not record the message envelope (the envelope + sender, and all envelope recipient addresses in the domain mailbox the + message was sent to), then mail will be lost or misdirected regardless + of which software you use to access the mailbox. The mailbox cannot + actually be said to be a domain mailbox in this case; the defining + characteristic of a domain mailbox is that it records the envelope + correctly. The configuration of the MTA running on the server needs to + be fixed so that the envelope is properly recorded for every message it + receives. + +This rc stuff seems complicated. Does it have to be? + + The configuration file format is actually very simple; you don't need + to worry about most of it if you're not interested in using those + features. The simplest and most common getmail rc file configuration + will be for users who want to retrieve all mail from a single-user POP3 + mailbox, deliver those messages to a maildir or mbox file, and delete + the mail from the server. For maildir, that configuration is: +[options] +delete = True + +[retriever] +type = SimplePOP3Retriever +server = my-pop3-servername +username = my-pop3-username +password = my-pop3-password + +[destination] +type = Maildir +path = ~/Maildir/ + + For an mbox file, that configuration is: +[options] +delete = True + +[retriever] +type = SimplePOP3Retriever +server = my-pop3-servername +username = my-pop3-username +password = my-pop3-password + +[destination] +type = Mboxrd +path = ~/inbox + +How do I … + +How do I retrieve mail from multiple accounts? + + Create a separate getmail rc file for each account, and run getmail + with multiple --rcfile options. + + Of course, it's really easy to script this for a large number of rc-* + files. You might create a script in $HOME/bin/run-getmail.sh + containing: +#!/bin/sh +set -e +cd /path/to/my-rc-directory +rcfiles="" +for file in rc-* ; do + rcfiles="$rcfiles --rcfile $file" +done +exec /path/to/getmail $rcfiles $@ + + See any beginner's tutorial on Unix shell scripting for details. + +How do I get getmail to deliver messages to different mailboxes based on … + + If you want getmail to sort messages based on who they're from, or what + address appears in the To: or cc: header fields, or based on the + Subject: field contents, or anything like that, pick a filtering MDA + (like maildrop or procmail), and call it from a getmail MDA_external + destination. + +How do I stop getmail adding a Delivered-To: header to messages? + + Use the delivered_to [options] parameter. + +How do I stop getmail adding a Received: header to messages? + + Use the received [options] parameter. + +How do I make getmail deliver messages by re-injecting with SMTP? + + You don't need to. getmail can deliver to maildirs, mboxrd files, or + through arbitrary external MDAs. + + If you still think you need to, you can use getmail's external MDA + support to do so. + +How do I create a maildir? + + Use the maildirmake command, if you have it installed. Otherwise, run + the following command from your shell: +$ mkdir -p /path/to/Maildir/{cur,new,tmp} + + Some other maildir-aware programs ship with their own maildir-creation + programs; you can use those, or make the above shell command a + shellscript or alias if you like. + +How do I create an mboxrd file? + + Create a completely empty (i.e. zero bytes long) file via your + favourite method. The standard utility touch is commonly used: +$ touch /path/to/mboxrd + +How do I make getmail deliver messages to an mh folder? + + mh clients (and nmh, or "new mh" clients) include a command for + delivering a message into your mh folder. In nmh, this command is + called rcvstore. You use it as an external message delivery agent (MDA) + with getmail's MDA_external destination. Ensure your $HOME/.mh_profile + file is configured properly; getmail user Frankye Fattarelli suggests a + line like the following is necessary to indicate the path to your mh + mail root: +Path: Mail + + Then use MDA_external like this (which, after adjusting the path of the + command to reflect your mh/nmh installation, should work with either mh + or nmh): +[destination] +type = MDA_external +path = /usr/local/libexec/nmh/rcvstore +arguments = ("+inbox", ) + + Thanks to Frankye Fattarelli for contributing this answer. + +How do I run getmail in "daemon" mode? + + Use your system's cron utility to run getmail periodically if you wish + to have mail retrieved automatically at intervals. This is precisely + what cron is designed to do; there's no need to add special code to + getmail to do this. + + With a reasonably standard system cron utility, a crontab(5) entry like + the following will make getmail retrieve mail every hour: +0 * * * * /usr/local/bin/getmail --quiet + +How do I make getmail stop after retrieving X messages so that the server +actually flushes deleted messages? + + Use the max_messages_per_session option to limit the number of messages + getmail will process in a single session. Some users with flaky servers + use this option to reduce the chances of seeing messages more than once + if the server dies in mid-session. + +How do I make getmail retrieve mail from Hotmail? + + Well, you could write a retriever that speaks Hotmail's proprietary, + undocumented, and unsupported access protocol (or pay me to write one), + or simply set up the POP3 proxy from the httpmail package, and have + getmail retrieve mail from that POP3 proxy. + +I'm using getmail. How do I make it … + + These are supplementary questions I occasionally see about doing + various things to enhance a getmail setup. The solution to many of them + is to use a standard Unix technique of some sort to make the system + behave in a certain manner, or otherwise change the behaviour of + something that's actually outside of getmail proper. + +I'm running getmail from cron. How do I temporarily stop it? + + Some people ask about temporarily stopping getmail from running from a + cron job, possibly because the mail server is down and they don't want + to see the warnings cron mails them. + + The easiest method is to comment out getmail from your crontab file: + 1. Run +$ crontab -e + to edit your crontab file. + 2. Place a # (pound) character at the start of the line containing the + call to getmail. + 3. Save the changed file. + + When you want to re-enable getmail, edit the file again and un-do the + above change. + + If you need to do this on a regular basis, you can instead use a "flag + file" to tell the system whether or not to run getmail: + + Change your cron job or shellscript that normally launches getmail to + check for the presence of a certain file first, and have it not run + getmail if that file is present. For example, your crontab entry could + be changed to do this: + [ -f ~/.getmail/do-not-run ] \|\| /path/to/getmail + + When you don't want getmail to run, touch that file: + $ touch ~/.getmail/do-not-run + + When you want getmail to run again, delete it: + $ rm -f ~/.getmail/do-not-run + + This is even safe for scripting, as creating and removing the file are + atomic operations under Unix. + +How do I stop multiple instances of getmail from running at the same time? + + getmail has no problems running multiple instances in parallel, though + you shouldn't attempt to use the same getmail rc file from two + different instances at the same time. If you need to prevent two + instances of getmail from running simultaneously, use any standard Unix + method of providing a mutex for this purpose. One example would be to + run getmail under a program like setlock (part of the daemontools + package). Change your script or crontab file to invoke getmail like + this: +/path/to/setlock -n /path/to/lockfile /path/to/getmail [getmail options] + + There are other programs that provide functionality similar to setlock. + +Using getmail with other software + + getmail user Frankye Fattarelli contributed to the following questions + about integrating getmail with SpamAssassin and ClamAV. + +How do I use SpamAssassin with getmail? + + SpamAssassin can be run in standalone mode or in a client/server + configuration. In both configurations, SpamAssassin accepts a wide + variety of arguments; please refer to SpamAssassin's manual pages or + online documentation for details. + + To filter messages through SpamAssassin in a client/server + configuration (i.e. with the spamd daemon), use a configuration like + this: +[filter] +type = Filter_external +path = /usr/local/bin/spamc +arguments = ("-s 10000", ) + + The value supplied to the -s option is the maximum message size + accepted (in bytes). The default is 250k. + + A similar configuration without the spamd daemon would be: +[filter] +type = Filter_external +path = /usr/local/bin/spamassassin +arguments = ("--report", ) + + The --report option sends the message to the various spam-blocker + databases and tags it as spam in your bayesian database. + + Note that if you are using Bayesian (learning) filtering, and you've + put your SpamAssassin filter after any getmail Filter_classifier, you + may have a problem with your learning filter learning getmail's header + fields. That is, the headers added by the other filters may get + learned, and affect your database. To prevent this, ensure that + SpamAssassin ignores these fields by adding the following to your + SpamAssassin configuration: +bayes_ignore_header X-getmail-filter-classifier + +How do I use ClamAV with getmail? + + You should also read this message in the getmail users' mailing list + archives and the ClamAV documentation if you want to use ClamAV with + getmail. + + ClamAV, like SpamAssassin, can by used in standalone or client/server + configurations. In either case, you need to add the StreamSaveToDisk + option to your clamav.conf file to enable scanning from stdin. + + To use ClamAV without the clamd daemon, use a filter configuration like + this: +[filter] +type = Filter_classifier +path = /usr/local/bin/clamscan +arguments = ("--stdout", "--no-summary", + "--mbox", "--infected", "-") +exitcodes_drop = (1,) + + The above assumes you do not want the infected emails to be delivered. + If you do want them delivered, you would use a slightly different + configuration: +[filter] +type = Filter_classifier +path = /usr/local/bin/clamscan +arguments = ("--stdout", "--no-summary", + "--mbox", "--infected", "-") +exitcodes_keep = (0,1) + + To use ClamAV with the clamd daemon, use a filter configuration like + this: +[filter] +type = Filter_classifier +path = /usr/local/bin/clamdscan +arguments = ("--stdout", "--disable-summary", "-") +exitcodes_drop = (1, ) + + As with Clamscan (above), if you do want the infected messages + delivered instead of dropped, you should modify your configuration as + follows: +[filter] +type = Filter_classifier +path = /usr/local/bin/clamdscan +arguments = ("--stdout", "--disable-summary", "-") +exitcodes_keep = (0,1) + + You may find it necessary to specify the paths of some decompression + utilities used by ClamAV with additional arguments like: +arguments = ( …, + "--unzip=/usr/local/bin/unzip", + "--unrar=/usr/local/bin/unrar", + "--unarj=/usr/local/bin/unarj", + "--lha=/usr/local/bin/lha", + "--jar=/usr/local/bin/unzip", + "--tar=/usr/bin/tar", + "--tgz=/usr/bin/tar" + + Note: if you want to use the daemonized (client/server) version of + ClamAV, ensure that your clamav.conf file contains: +ScanMail + + The paths to the various decompression utilities must be specified in + this file as well. + + See the following mailing list message from Frankye Fattarelli for + additional notes on using ClamAV with getmail: + http://marc.theaimsgroup.com/?l=getmail&m=109128345509273&w=2 + +Getting prettier output from ClamAV + + Using getmail's Filter_classifier, the output of your filtering program + (in this case ClamAV) is placed into a X-getmail-filter-classifier: + header field in the message. This can make auditing the actions of + filters difficult if you use multiple filters and cannot tell which + filter added which line. + + To correct this, you can use an additional filter to change the name of + the added filter header lines immediately after each filter is run. For + example, reformail, from the maildrop package (which is in turn part of + the Courier MTA ) can be used in this fashion to rename the added + header fields (say, to "X-mypersonalmailscan") with a filter + configuration like this: +type = Filter_external +path = /usr/local/bin/reformail +arguments = ("-R", "X-getmail-filter-classifier:", + "X-mypersonalmailscan:") + + Simply ensure ClamAV is invoked as the first filter, and this is + invoked as the second filter (or immediately after the ClamAV filter, + if it is the second, third, etc. filter). + +How do I use F-Prot with getmail? + + getmail user Kai Raven reports that getmail and F-Prot work fine + together with the following getmailrc filter configuration: +[filter] +type = Filter_external +path = /usr/local/bin/f-prot-wrapper.sh + + The wrapper script f-prot-wrapper.sh is a small shellscript by Ali Onur + Cinar, and can be downloaded from his website. + +How do I use procmail with getmail? + + Simply invoke procmail as an external MDA. procmail requires that one + of the following be true: + * that the message begin with a Unix "From " line (the mbox message + delimiter) + * that procmail is invoked with the -f option supplying the envelope + sender, so that it may generate the "From " line + + To have getmail generate and prepend the "From " line to the start of + the message, set the MDA_external parameter unixfrom to True: +[destination] +type = MDA_external +path = /path/to/procmail +unixfrom = True + + To supply the -f option to procmail, do something like this: +[destination] +type = MDA_external +path = /path/to/procmail +arguments = ("-f", "%(sender)") + +How do I use maildrop with getmail? + + Simply invoke maildrop as an external MDA. maildrop requires that the + message begin with a Unix "From " line (the mbox message delimiter), so + you'll need to either set the MDA_external parameter unixfrom to True, + or supply arguments that tell maildrop to recreate this line. One of + the following would be fine: +[destination] +type = MDA_external +path = /path/to/maildrop +arguments = ("-f", "%(sender)") + + Or: +[destination] +type = MDA_external +path = /path/to/maildrop +unixfrom = True + + If you want to specify a maildrop rc file as one of its arguments, that + would be something like: +[destination] +type = MDA_external +path = /path/to/maildrop +arguments = ("-f", "%(sender)", "~/.maildroprc") + +How do I use TMDA with getmail? + + Simply use the Filter_TMDA module as a message filter: +[filter-X] +type = Filter_TMDA + + See the documentation for details on optional parameters to the + Filter_TMDA module. + +How can I get Gmail labels with getmail? + + As of getmail version 4.34.0, getmail retrieves the labels and other + metadata that Gmail makes available via an IMAP extension, and records + that information in the message headers X-GMAIL-LABELS:, + X-GMAIL-THRID:, and X-GMAIL-MSGID:. + +I think I found this bug in getmail … + + I get frequent reports like the following, which aren't bugs in + getmail. Please read them before reporting them to me. + +getmail doesn't download all my mail from Gmail … + + There's a couple of different problems here. One is that Google's Gmail + service violates the POP3 protocol by removing messages from the POP3 + view of the mailbox without the user issuing a DELE command. They do + this as soon as an RETR command is given, so if getmail tries to + download a message and it fails for any reason (delivery fails due to a + full disk, or the Gmail server fails to respond, or the network + connection dies before the transfer is complete, or the Gmail server + fails to respond to the QUIT command, or …), the next time getmail + connects to that Gmail account, Gmail will have "helpfully" deleted the + message from the POP3 mailbox, even though getmail never issued a DELE + command. So Gmail silently destroys mail, from a POP3 perspective. + There's nothing getmail can do about this. + + Note this feature of Gmail is not well-publicized. The only mention I + can find of it is here: + http://mail.google.com/support/bin/answer.py?answer=13291&topic=1555 + + The other issue here is that Google doesn't include mail from your + trash or spam folders in the POP3 view, so getmail can't see those + messages either. That's generally less of an issue, provided their spam + filters never give false positive results (ha!). + +FutureWarning: %u/%o/%x/%X of negative int will return a signed string in +Python 2.4 and up + + Various people have reported this "bug" in getmail, where they see the + following warning when getmail is run: +/usr/lib/python2.3/optparse.py:668: FutureWarning: %u/%o/%x/%X of negative int w +ill return a signed string in Python 2.4 and up + return ("<%s at 0x%x: %r>" + + This warning is a bug in Python 2.3.4's optparse.py module, not in + getmail. Feel free to report it to the Python team if the most recent + release of Python hasn't fixed it. I reported it in June, 2004. + +AttributeError: 'module' object has no attribute 'fsync' + + Various people have reported this "bug" in getmail — it's actually a + bug in some versions of Python 2.3.X. It was fixed in Python version + 2.3.3. getmail 4 detects problematic versions of Python and refuses to + run, but you can still encounter this problem with getmail version 3 if + you try to run it with a broken Python version. + +operation error (SimplePOP3Retriever: [...] does not uniquely identify +messages [...] see documentation or use BrokenUIDLPOP3Retriever instead + + The server you're trying to use does not properly uniquely identify + messages (getmail noticed when it saw the same "unique" identifier + twice in the same mailbox at the same time). getmail needs these + identifiers to be unique so that it can properly tell the difference + between new and old messages. + + If you see this error message, and you've configured getmail to + retrieve and immediately delete all messages, just switch to using the + BrokenUIDLPOP3Retriever class (or its SSL variant) -- it'll work fine. + + If you see this error message, and you're trying to leave messages on + the server after retrieval (permanently, or for a few days with + delete_after), you have a few options to try to resolve it: + * If your provider also offers IMAP access to your mailbox, try one + of the IMAP retrievers instead. + * Change your configuration so you're not leaving messages on the + server, and use BrokenUIDLPOP3Retriever instead. + * Talk to your mail hosting provider, and see if they can fix their + POP3 software so that it doesn't have this problem any more. + +MemoryError on OS X + + If you see errors like this while running getmail on Macintosh OS X: +python2.5(27172) malloc: * vm_allocate(size=15699968) failed (error code=3) +python2.5(27172) malloc: * error: can't allocate region +python2.5(27172) malloc: * set a breakpoint in szone_error to debug +[...] + + ... which then end with MemoryError, please report the problem to + Apple. The OS X implementation of realloc() is broken, and there's + nothing getmail can do about it. + +MemoryError when using IMAP + + If you see errors like this while running getmail configured to + retrieve mail via IMAP or IMAP-over-SSL: +Python(24006) malloc: * mmap(size=9875456) failed (error code=12) +[...] + + ... which then end with MemoryError, you've run into a bug in Python's + IMAP library. It's fixed in the most recent versions of Python 2.5 and + 2.6. This bug can cause getmail to grow to a huge size, vastly out of + proportion to the size of the message it's retrieving, at which point + Python may fail or be killed when the system runs out of memory. + + Upgrade your Python installation to the newest Python 2.5 or 2.6 + version to fix the problem, or use POP3 instead of IMAP to work around + it.
[-] [+]	Added	getmail-4.46.0.tar.bz2/docs/troubleshooting.txt ^
@@ -0,0 +1,270 @@ + Link: Contents Up Index: Charles Cazabon's Software + + getmail documentation + + This is the documentation for getmail version 4. Version 4 includes + numerous changes from version 3.x; if you are using getmail version 3, + please refer to the documentation included with that version of the + software. + + getmail is Copyright (c) 1998-2009 Charles Cazabon. + + getmail is licensed under the GNU General Public License version 2 (only). + If you wish to obtain a license to distribute getmail under other terms, + please contact me directly. + + Troubleshooting problems + + This section of the documentation is to be added to as getmail version 4 + progresses through beta testing to release state. If you have suggestions + for additions or changes to this documentation, please send them to the + mailing list or me. + +Error messages + + getmail may output various diagnostic error messages. The common ones and + their meanings are given below. + + ImportError: getmail version 4 requires Python version 2.3.3 or later + + You tried to run getmail 4 with a version of Python prior to Python 2.3.3. + This is unsupported. If you cannot install a newer Python alongside your + current version, please use getmail version 3, which supports Python 1.5.2 + and later. + + Configuration error: ... + + getmail detected an error in your configuration. Check your getmail rc + file(s). getmail will do its best to point out the exact cause of the + error. Some of the specific errors it may find include the following. + + Configuration error: missing required configuration parameter name + + A class object in your getmail rc file requires the parameter name, but it + was not found in the appropriate section of the file. + + Configuration error: configuration value name (value) not of required type + type (why) + + The configuration parameter name must be of type type, but the supplied + value value does not appear to be of that type. Further information may be + present in why. + + The getmail documentation contains descriptions of the syntax for each + parameter type. + + Configuration error: maildir path missing trailing / + + Maildir paths must start with dot or slash and end with a slash. + + Configuration error: not a maildir (path) + + The specified maildir path path does not appear to be a valid maildir. + Check to ensure that it is a valid maildir, and that getmail has + permission to write to it. + + Configuration error: ... (path: maildir subdirectory "path" does not exist) + + The specified maildir path path does not appear to be a valid maildir, as + it is missing one of the required subdirectories. Check to ensure that it + is a valid maildir and that getmail has permission to write to it. + + Configuration error: not an mboxrd file (path) + + The specified mboxrd path path does not appear to be a valid mboxrd file. + To avoid corrupting files in the event of a user typo, getmail will not + deliver messages to files that do not appear to be valid mboxrd files. + + Configuration error: mboxrd does not exist + + The specified mboxrd does not exist. getmail will not create mbox files; + ensure they exist before trying to deliver to them. + + Configuration error: the fieldname header field does not record the envelope + recipient address + + In a multidrop retriever configuration, you specified that the envelope + recipient was recorded in a header field that getmail knows does not + actually record that information. + + Configuration error: refuse to invoke external commands as root or GID 0 by + default + + By default, getmail will not invoke external commands (in destinations or + filters) when it is running with root privileges, for security reasons. + See the documenation for possible solutions. + + Configuration error: no such command path + + An external command was specified as being located at path path, but the + command executable was not found at that location. + + Configuration error: path not executable + + A specified external command at path path was found to not be an + executable file. + + Configuration error: destination specifies section name section which does + not exist + + A destination in the getmail rc file refers to another rc file section + named section, but that section was not found in the file. + + Retrieval error ... + + getmail detected an error while trying to retrieve a message. Some of the + specific errors it may find include the following. + + Retrieval error: server ... is broken; ... + + The server claimed to have a particular message, but when getmail tried to + retrieve it, the server returned an empty response in violation of the POP + or IMAP protocol. getmail will skip on to the next message. + + This problem is almost always with an MSExchange server, and is due to + bugs in MSExchange. Delete the offending message from the mailbox via the + webmail interface if you don't want to see this error message, and report + the bug to the server administrator or Microsoft. + + Delivery error ... + + getmail detected an error after retrieving a message but before delivery + was successfully completed. Some of the specific errors it may find + include the following. + + Delivery error: maildir delivery process failed (refuse to deliver mail as + root) + + getmail will not deliver to a maildir as the root user. You may specify an + alternate user to deliver as with the user directive in the destination + section of your getmailrc file, or let getmail default to the user who is + the owner of the maildir. + + Delivery error: mbox delivery process failed (refuse to deliver mail as + root) + + getmail will not deliver to an mbox file as the root user. You may specify + an alternate user to deliver as with the user directive in the destination + section of your getmailrc file, or let getmail default to the user who is + the owner of the mbox file. + + Delivery error: mbox delivery process failed (not an mboxrd file) + + The specified mbox file does not appear to be a valid mbox file. + + Error: ... + + getmail detected an operational error. getmail will do its best to point + out the exact cause of the error. Common causes are failures to connect to + a remote mail server, timeouts during network operations, and other + transient failures. + + Error: server-info does not uniquely identify messages ... + + The POP3 server for this particular account was not able to uniquely + identify the messages in the mailstore. You can use the + BrokenUIDLPOP3Retriever class with this server instead, but functionality + is limited because of the inability to identify messages properly. + + Error: server-info failed to identify message X in UIDL output ... + + The POP3 server for this particular account completely failed to identify + one of the messages in the mailstore when the UIDL command was issued. The + POP server is in violation of the POP3 protocol, and getmail has no way to + identify the message in question. + + The most common cause of this is servers that use the contents of the + Message-ID: header field as the UIDL value for the message - some messages + (usually spam) lack a Message-ID: header field entirely, causing these + servers to emit blank UIDL values for these messages, which is not + permitted by the POP3 protocol. You may be able to work around the problem + by deleting the problematic message(s) from the mailstore by other means + (such as a webmail interface provided by your POP3 mailhost). + + Otherwise, you'll need to either ask the postmaster of the POP3 mail host + to fix the POP3 software they're using. In the meantime, you can use the + BrokenUIDLPOP3Retriever class with this server instead, but functionality + is limited because of the inability to identify messages properly. + + Python(...) malloc: *** mmap(...) failed (...) + + ... followed by an Unhandled exception block and then MemoryError. + + getmail ran out of memory, usually due to a bug in Python's IMAP library + which was fixed in early 2008. + + If you are using IMAP and run into this problem retrieving messages that + aren't hundreds of megabytes in size, you can almost certainly fix it by + upgrading your Python installation to the latest 2.5.x or 2.6.x release. + Note that if you switch from Python 2.5.x to Python 2.6.x, you'll need to + re-install getmail with python setup.py install from the getmail source + directory. + +Warning messages + + getmail may output various diagnostic warning messages. The common ones + and their meanings are given below. + + Warning: ... + + getmail detected a condition which might be problematic. Some of the + specific warnings it may find include the following. + + Warning: ignoring unknown parameter "parameter_name" + + A getmail rc file contained an unknown parameter. This usually indicates + that you've put the parameter in the wrong section of the file (such as + putting the read_all parameter in the [retriever] section instead of in + the [options] section). + + Warning: filter filter returned fewer headers (X) than supplied (Y) + + A message filter appeared to incorrectly remove header fields from the + header of a message which it handled. getmail warns you about this so that + you can check your filter for proper operation. Filters should add + information to the message header or leave it alone; check the + configuration for the filter program you are using. + +Unexpected Behaviour + + If getmail is behaving in a manner other that you expected, see the + following sections. + + getmail uses the wrong hostname for my machine + + If getmail records a hostname other than the "right" one for your host (in + its Received: trace header fields), check your /etc/hosts file and make + sure the "right" name is the first hostname listed for any of the + addresses of the machine. + + getmail puts "unknown" in the Delivered-To: or Return-Path:header field + + getmail records the envelope recipient address in the Delivered-To: header + field, and the envelope sender in the Return-Path: header field. If this + information is not available (because you're not using a multidrop + retriever class, or the MTA on the POP/IMAP server is broken, for + example), getmail uses the string "unknown". You can disable the creation + of the Delivered-To: header field if you wish. + + getmail isn't replacing my command argument "%(recipient)" with the message + recipient address + + The %(recipient), %(local), and %(domain) replacement strings are only + replaced if the message is retrieved with a multidrop retriever class; + otherwise, getmail does not "know" the recipient address of the message, + and therefore cannot perform this replacement. + + getmail seems to take longer than expected to initialize + + If getmail takes more than a few seconds to initialize, run the following + command to test: + + python -c "import socket; print socket.getfqdn()" + + If this seems to take a similarly long period of time to complete, the + delay is in finding the fully-qualified hostname of your system. The fix + is to ensure you have a valid mapping of address-to-hostname for all the + addresses in your system. You can do this in your /etc/hosts file, in your + authoritative content DNS server, or in another system-specific manner - + please contact your OS vendor (or its public support mailing list) for + assistance.
[-] [+]	Changed	getmail-4.46.0.tar.bz2/getmail ^
@@ -34,6 +34,7 @@ 'received', 'message_log_verbose', 'message_log_syslog', + 'fingerprint', ) options_int = ( 'delete_after', @@ -85,6 +86,7 @@ 'message_log_verbose' : False, 'message_log_syslog' : False, 'logfile' : None, + 'fingerprint' : False, } @@ -393,11 +395,13 @@ log.debug('retriever %s finished\n' % retriever) try: if idle and not retriever.supports_idle: - log.info('--idle given, but chosen retriever does not support' - 'IDLE\n') + log.info('--idle given, but retriever does not support IDLE\n') + idle = False + if idle and sys.version_info < (2, 5, 0): + log.info('--idle requires Python 2.5 or higher\n') idle = False - if not errorexit and idle: + if idle and not errorexit: # TODO # Okay, so what should really happen here is that when go_idle # returns, getmail should use the existing connection to check @@ -414,8 +418,12 @@ # value of idling, a failed connection will cause it to become # False, which will make the main go() loop reconnect, which is # what we want. + # Expunge and close the mailbox to prevent the same messages + # being pulled again in some configurations. + retriever.close_mailbox() try: idling = retriever.go_idle(idle) + # Returned from idle configs.append(configs[0]) continue except KeyboardInterrupt, o: @@ -493,6 +501,11 @@ help='operate more verbosely (may be given multiple times)' ) overrides.add_option( + '--fingerprint', + dest='override_fingerprint', action='store_true', + help='show SSL/TLS fingerprint and connection information' + ) + overrides.add_option( '-q', '--quiet', dest='override_verbose', action='store_const', const=0, @@ -591,6 +604,7 @@ 'message_log' : defaults['message_log'], 'message_log_verbose' : defaults['message_log_verbose'], 'message_log_syslog' : defaults['message_log_syslog'], + 'fingerprint' : defaults['fingerprint'], } # Python's ConfigParser .getboolean() couldn't handle booleans in # the defaults. Submitted a patch; they fixed it a different way. @@ -805,7 +819,7 @@ ) # Apply overrides from commandline - for option in ('read_all', 'delete', 'verbose'): + for option in ('read_all', 'delete', 'verbose', 'fingerprint'): val = getattr(options, 'override_%s' % option) if val is not None: log.debug('overriding option %s from commandline %s\n'
[-] [+]	Changed	getmail-4.46.0.tar.bz2/getmail.spec ^
@@ -2,7 +2,7 @@ Summary: POP3 mail retriever with reliable Maildir delivery Name: getmail -Version: 4.43.0 +Version: 4.46.0 Release: 1 License: GPL Group: Applications/Internet @@ -52,6 +52,33 @@ %{python_sitelib}/getmailcore/ %changelog +* Sun Apr 06 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.46.0 + +* Sun Apr 06 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.46.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.45.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.45.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + +* Sun Mar 30 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + +* Sat Mar 22 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + +* Sat Mar 22 2014 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> +-update to version 4.44.0 + * Sun Aug 25 2013 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca> -update to version 4.43.0
[-] [+]	Changed	getmail-4.46.0.tar.bz2/getmailcore/__init__.py ^
@@ -16,7 +16,7 @@ raise ImportError('getmail version 4 requires Python version 2.3.3' ' or later') -__version__ = '4.43.0' +__version__ = '4.46.0' __all__ = [ 'baseclasses',
[-] [+]	Changed	getmail-4.46.0.tar.bz2/getmailcore/_retrieverbases.py ^
@@ -53,6 +53,124 @@ except ImportError: pass +# hashlib only present in python2.5, ssl in python2.6; used together +# in SSL functionality below +try: + import ssl +except ImportError: + ssl = None +try: + import hashlib +except ImportError: + hashlib = None + +# If we have an ssl module: +if ssl: + # Is it recent enough to have hostname matching (Python 3.2+)? + try: + ssl_match_hostname = ssl.match_hostname + except AttributeError: + # Running a Python with no hostname matching + def _dnsname_match(dn, hostname, max_wildcards=1): + """Matching according to RFC 6125, section 6.4.3 + http://tools.ietf.org/html/rfc6125#section-6.4.3 + """ + pats = [] + if not dn: + return False + + parts = dn.split(r'.') + leftmost = parts[0] + remainder = parts[1:] + + wildcards = leftmost.count('') + if wildcards > max_wildcards: + # Issue #17980: avoid denials of service by refusing more + # than one wildcard per fragment. A survery of established + # policy among SSL implementations showed it to be a + # reasonable choice. + raise getmailOperationError( + "too many wildcards in certificate DNS name: " + repr(dn)) + + # speed up common case w/o wildcards + if not wildcards: + return dn.lower() == hostname.lower() + + # RFC 6125, section 6.4.3, subitem 1. + # The client SHOULD NOT attempt to match a presented identifier + # in which the wildcard character comprises a label other than + # the left-most label. + if leftmost == '': + # When '' is a fragment by itself, it matches a non-empty + # dotless fragment. + pats.append('[^.]+') + elif leftmost.startswith('xn--') or hostname.startswith('xn--'): + # RFC 6125, section 6.4.3, subitem 3. + # The client SHOULD NOT attempt to match a presented identifier + # where the wildcard character is embedded within an A-label or + # U-label of an internationalized domain name. + pats.append(re.escape(leftmost)) + else: + # Otherwise, '' matches any dotless string, e.g. www* + pats.append(re.escape(leftmost).replace(r'\', '[^.]')) + + # add the remaining fragments, ignore any wildcards + for frag in remainder: + pats.append(re.escape(frag)) + + pat = re.compile(r'\A' + r'\.'.join(pats) + r'\Z', re.IGNORECASE) + return pat.match(hostname) + + + def ssl_match_hostname(cert, hostname): + """Verify that cert (in decoded format as returned by + SSLSocket.getpeercert()) matches the hostname. RFC 2818 and + RFC 6125 rules are followed, but IP addresses are not accepted + for hostname. + + getmailOperationError is raised on failure. On success, the function + returns nothing. + """ + if not cert: + raise ValueError("empty or no certificate, ssl_match_hostname " + "needs an SSL socket or SSL context with " + "either CERT_OPTIONAL or CERT_REQUIRED") + dnsnames = [] + san = cert.get('subjectAltName', ()) + for key, value in san: + if key == 'DNS': + if _dnsname_match(value, hostname): + return + dnsnames.append(value) + if not dnsnames: + # The subject is only checked when there is no dNSName entry + # in subjectAltName + for sub in cert.get('subject', ()): + for key, value in sub: + # XXX according to RFC 2818, the most specific + # Common Name must be used. + if key == 'commonName': + if _dnsname_match(value, hostname): + return + dnsnames.append(value) + if len(dnsnames) > 1: + raise getmailOperationError("hostname %s " + "doesn't match either of %s" + % (hostname, ', '.join(map(repr, dnsnames)))) + elif len(dnsnames) == 1: + raise getmailOperationError("hostname %s " + "doesn't match %s" + % (hostname, dnsnames[0])) + else: + raise getmailOperationError("no appropriate commonName or " + "subjectAltName fields were found") + +try: + from email.header import decode_header +except ImportError, o: + # python < 2.5 + from email.Header import decode_header + from getmailcore.compatibility import * from getmailcore.exceptions import * from getmailcore.constants import * @@ -112,6 +230,9 @@ EAI_FAIL = getattr(socket, 'EAI_FAIL', NO_OBJ) +# Constant for POPSSL +POP3_SSL_PORT = 995 + # # Mix-in classes # @@ -142,6 +263,55 @@ ####################################### +class POP3_SSL_EXTENDED(poplib.POP3_SSL): + # Extended SSL support for POP3 (certificate checking, + # fingerprint matching, cipher selection, etc.) + + def __init__(self, host, port=POP3_SSL_PORT, keyfile=None, + certfile=None, ssl_version=None, ca_certs=None, + ssl_ciphers=None): + self.host = host + self.port = port + self.keyfile = keyfile + self.certfile = certfile + self.ssl_version = ssl_version + self.ca_certs = ca_certs + self.ssl_ciphers = ssl_ciphers + + self.buffer = '' + msg = "getaddrinfo returns an empty list" + self.sock = None + for res in socket.getaddrinfo(self.host, self.port, 0, + socket.SOCK_STREAM): + (af, socktype, proto, canonname, sa) = res + try: + self.sock = socket.socket(af, socktype, proto) + self.sock.connect(sa) + except socket.error, msg: + if self.sock: + self.sock.close() + self.sock = None + continue + break + if not self.sock: + raise socket.error(msg) + extra_args = {} + if self.ssl_version: + extra_args['ssl_version'] = self.ssl_version + if self.ca_certs: + extra_args['cert_reqs'] = ssl.CERT_REQUIRED + extra_args['ca_certs'] = self.ca_certs + if self.ssl_ciphers: + extra_args['ciphers'] = self.ssl_ciphers + + self.file = self.sock.makefile('rb') + self.sslobj = ssl.wrap_socket(self.sock, self.keyfile, + self.certfile, extra_args) + self._debugging = 0 + self.welcome = self._getresp() + + +####################################### class Py24POP3SSLinitMixIn(object): '''Mix-In class to do POP3 over SSL initialization with Python 2.4's poplib.POP3_SSL class. @@ -154,8 +324,39 @@ 'SSL not supported by this installation of Python' ) (keyfile, certfile) = check_ssl_key_and_cert(self.conf) - try: - if keyfile: + ca_certs = check_ca_certs(self.conf) + ssl_version = check_ssl_version(self.conf) + ssl_fingerprints = check_ssl_fingerprints(self.conf) + ssl_ciphers = check_ssl_ciphers(self.conf) + using_extended_certs_interface = False + try: + if ca_certs or ssl_version or ssl_ciphers: + using_extended_certs_interface = True + # Python 2.6 or higher required, use above class instead of + # vanilla stdlib one + msg = '' + if keyfile: + msg += 'with keyfile %s, certfile %s' % (keyfile, certfile) + if ssl_version: + if msg: + msg += ', ' + msg += ('using protocol version %s' + % self.conf['ssl_version'].upper()) + if ca_certs: + if msg: + msg += ', ' + msg += 'with ca_certs %s' % ca_certs + + self.log.trace( + 'establishing POP3 SSL connection to %s:%d %s' + % (self.conf['server'], self.conf['port'], msg) + + os.linesep + ) + self.conn = POP3_SSL_EXTENDED( + self.conf['server'], self.conf['port'], keyfile, certfile, + ssl_version, ca_certs, ssl_ciphers + ) + elif keyfile: self.log.trace( 'establishing POP3 SSL connection to %s:%d with ' 'keyfile %s, certfile %s' @@ -173,6 +374,41 @@ self.conn = poplib.POP3_SSL(self.conf['server'], self.conf['port']) self.setup_received(self.conn.sock) + if ssl and hashlib: + sslobj = self.conn.sslobj + peercert = sslobj.getpeercert(True) + ssl_cipher = sslobj.cipher() + if ssl_cipher: + ssl_cipher = '%s:%s:%s' % ssl_cipher + if not peercert: + actual_hash = None + else: + actual_hash = hashlib.sha256(peercert).hexdigest().lower() + else: + actual_hash = None + ssl_cipher = None + + # Ensure cert is for server we're connecting to + if ssl and self.conf['ca_certs']: + ssl_match_hostname(self.conn.sslobj.getpeercert(), + self.conf['server']) + + if ssl_fingerprints: + if not actual_hash: + raise getmailOperationError( + 'socket ssl_fingerprints mismatch (no cert provided)' + ) + + any_matches = False + for expected_hash in ssl_fingerprints: + if expected_hash == actual_hash: + any_matches = True + if not any_matches: + raise getmailOperationError( + 'socket ssl_fingerprints mismatch (got %s)' + % actual_hash + ) + except poplib.error_proto, o: raise getmailOperationError('POP error (%s)' % o) except socket.timeout: @@ -202,6 +438,15 @@ 'SSL not supported by this installation of Python' ) (keyfile, certfile) = check_ssl_key_and_cert(self.conf) + ca_certs = check_ca_certs(self.conf) + ssl_version = check_ssl_version(self.conf) + ssl_fingerprints = check_ssl_fingerprints(self.conf) + ssl_ciphers = check_ssl_ciphers(self.conf) + if ca_certs or ssl_version or ssl_ciphers or ssl_fingerprints: + raise getmailConfigurationError( + 'SSL extended options are not supported by this' + ' installation of Python' + ) try: if keyfile: self.log.trace( @@ -220,6 +465,7 @@ + os.linesep ) self.conn = POP3SSL(self.conf['server'], self.conf['port']) + self.setup_received(self.conn.rawsock) except poplib.error_proto, o: raise getmailOperationError('POP error (%s)' % o) @@ -259,6 +505,35 @@ + os.linesep) +####################################### +class IMAP4_SSL_EXTENDED(imaplib.IMAP4_SSL): + # Similar to above, but with extended support for SSL certificate checking, + # fingerprints, etc. + def __init__(self, host='', port=imaplib.IMAP4_SSL_PORT, keyfile=None, + certfile=None, ssl_version=None, ca_certs=None, + ssl_ciphers=None): + self.ssl_version = ssl_version + self.ca_certs = ca_certs + self.ssl_ciphers = ssl_ciphers + imaplib.IMAP4_SSL.__init__(self, host, port, keyfile, certfile) + + def open(self, host='', port=imaplib.IMAP4_SSL_PORT): + self.host = host + self.port = port + self.sock = socket.create_connection((host, port)) + extra_args = {} + if self.ssl_version: + extra_args['ssl_version'] = self.ssl_version + if self.ca_certs: + extra_args['cert_reqs'] = ssl.CERT_REQUIRED + extra_args['ca_certs'] = self.ca_certs + if self.ssl_ciphers: + extra_args['ciphers'] = self.ssl_ciphers + + self.sslobj = ssl.wrap_socket(self.sock, self.keyfile, self.certfile, + extra_args) + self.file = self.sslobj.makefile('rb') + ####################################### class IMAPSSLinitMixIn(object): @@ -272,8 +547,39 @@ 'SSL not supported by this installation of Python' ) (keyfile, certfile) = check_ssl_key_and_cert(self.conf) - try: - if keyfile: + ca_certs = check_ca_certs(self.conf) + ssl_version = check_ssl_version(self.conf) + ssl_fingerprints = check_ssl_fingerprints(self.conf) + ssl_ciphers = check_ssl_ciphers(self.conf) + using_extended_certs_interface = False + try: + if ca_certs or ssl_version or ssl_ciphers: + using_extended_certs_interface = True + # Python 2.6 or higher required, use above class instead of + # vanilla stdlib one + msg = '' + if keyfile: + msg += 'with keyfile %s, certfile %s' % (keyfile, certfile) + if ssl_version: + if msg: + msg += ', ' + msg += ('using protocol version %s' + % self.conf['ssl_version'].upper()) + if ca_certs: + if msg: + msg += ', ' + msg += 'with ca_certs %s' % ca_certs + + self.log.trace( + 'establishing IMAP SSL connection to %s:%d %s' + % (self.conf['server'], self.conf['port'], msg) + + os.linesep + ) + self.conn = IMAP4_SSL_EXTENDED( + self.conf['server'], self.conf['port'], keyfile, certfile, + ssl_version, ca_certs, ssl_ciphers + ) + elif keyfile: self.log.trace( 'establishing IMAP SSL connection to %s:%d with keyfile ' '%s, certfile %s' @@ -292,6 +598,41 @@ self.conn = imaplib.IMAP4_SSL(self.conf['server'], self.conf['port']) self.setup_received(self.conn.sock) + if ssl and hashlib: + sslobj = self.conn.ssl() + peercert = sslobj.getpeercert(True) + ssl_cipher = sslobj.cipher() + if ssl_cipher: + ssl_cipher = '%s:%s:%s' % ssl_cipher + if not peercert: + actual_hash = None + else: + actual_hash = hashlib.sha256(peercert).hexdigest().lower() + else: + actual_hash = None + ssl_cipher = None + + # Ensure cert is for server we're connecting to + if ssl and self.conf['ca_certs']: + ssl_match_hostname(self.conn.ssl().getpeercert(), + self.conf['server']) + + if ssl_fingerprints: + if not actual_hash: + raise getmailOperationError( + 'socket ssl_fingerprints mismatch (no cert provided)' + ) + + any_matches = False + for expected_hash in ssl_fingerprints: + if expected_hash == actual_hash: + any_matches = True + if not any_matches: + raise getmailOperationError( + 'socket ssl_fingerprints mismatch (got %s)' + % actual_hash + ) + except imaplib.IMAP4.error, o: raise getmailOperationError('IMAP error (%s)' % o) except socket.timeout: @@ -311,14 +652,25 @@ % (self.conf['server'], o) ) else: - raise getmailOperationError('socket error during connect (%s)' % o) + raise getmailOperationError('socket error during connect (%s)' + % o) except socket.sslerror, o: raise getmailOperationError( 'socket sslerror during connect (%s)' % o ) - self.log.trace('IMAP SSL connection %s established' % self.conn - + os.linesep) + fingerprint_message = ('IMAP SSL connection %s established' + % self.conn) + if actual_hash: + fingerprint_message += ' with fingerprint %s' % actual_hash + if ssl_cipher: + fingerprint_message += ' using cipher %s' % ssl_cipher + fingerprint_message += os.linesep + + if self.app_options['fingerprint']: + self.log.info(fingerprint_message) + else: + self.log.trace(fingerprint_message) # # Base classes @@ -1006,18 +1358,33 @@ % g['mailbox']) return mailboxes + def close_mailbox(self): + # Close current mailbox so deleted mail is expunged. One getmail + # user had a buggy IMAP server that didn't do the automatic expunge, + # so we do it explicitly here. + self.conn.expunge() + self.conn.close() + self.write_oldmailfile(self.mailbox_selected) + # And clear some state + self.mailbox_selected = False + self.mailbox = None + self.uidvalidity = None + self.msgnum_by_msgid = {} + self.msgid_by_msgnum = {} + self.sorted_msgnum_msgid = () + self._mboxuids = {} + self._mboxuidorder = [] + self.msgsizes = {} + self.oldmail = {} + self.__delivered = {} + def select_mailbox(self, mailbox): self.log.trace() assert mailbox in self.mailboxes, ( 'mailbox not in config (%s)' % mailbox ) if self.mailbox_selected is not False: - # Close current mailbox so deleted mail is expunged. - # Except one user reports that an explicit expunge is needed with - # his server, or else the mail is never removed from the mailbox. - self.conn.expunge() - self.conn.close() - self.write_oldmailfile(self.mailbox_selected) + self.close_mailbox() self._clear_state() @@ -1281,6 +1648,17 @@ + os.linesep) del self.oldmail[msgid] """ + # Some IMAP servers change the available capabilities after + # authentication, i.e. they present a limited set before login. + # The Python stlib IMAP4 class doesn't take this into account + # and just checks the capabilities immediately after connecting. + # Force a re-check now that we've authenticated. + (typ, dat) = self.conn.capability() + if dat == [None]: + # No response, don't update the stored capabilities + self.log.warn('no post-login CAPABILITY response from server\n') + else: + self.conn.capabilities = tuple(dat[-1].upper().split()) if 'IDLE' in self.conn.capabilities: self.supports_idle = True @@ -1304,7 +1682,7 @@ pass self.conn = None - def go_idle(self, folder, timeout=29*60): + def go_idle(self, folder, timeout=300): """Initiates IMAP's IDLE mode if the server supports it Waits until state of current mailbox changes, and then returns. Returns @@ -1313,11 +1691,11 @@ May throw getmailOperationError if the server refuses the IDLE setup (e.g. if the server does not support IDLE) - Default timeout is the maximum possible idle time according to RFC 2177. + Default timeout is 5 minutes. """ if not self.supports_idle: - self.log.warning('IDLE not supported, so not idling') + self.log.warning('IDLE not supported, so not idling\n') raise getmailOperationError( 'IMAP4 IDLE requested, but not supported by server' ) @@ -1376,12 +1754,7 @@ return try: if self.mailbox_selected is not False: - # Close current mailbox so deleted mail is expunged. - # Except one user reports that an explicit expunge is needed - # with his server, or else the mail is never removed from the - # mailbox. - self.conn.expunge() - self.conn.close() + self.close_mailbox() self.conn.logout() except imaplib.IMAP4.error, o: #raise getmailOperationError('IMAP error (%s)' % o) @@ -1431,13 +1804,14 @@ self.log.trace() msg = IMAPRetrieverBase._getmsgbyid(self, msgid) data = {} - for (name, val) in msg.headers(): + for (name, encoded_value) in msg.headers(): name = name.lower() - val = val.strip() - if name in data: - data[name].append(val) - else: - data[name] = [val] + for (val, encoding) in decode_header(encoded_value): + val = val.strip() + if name in data: + data[name].append(val) + else: + data[name] = [val] try: line = data[self.envrecipname][self.envrecipnum]
[-] [+]	Changed	getmail-4.46.0.tar.bz2/getmailcore/retrievers.py ^
@@ -99,6 +99,10 @@ ConfBool(name='delete_dup_msgids', required=False, default=False), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), ) received_from = None received_with = 'POP3-SSL' @@ -200,6 +204,10 @@ ConfBool(name='use_apop', required=False, default=False), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), ) received_with = 'POP3-SSL' @@ -266,6 +274,10 @@ ConfString(name='envelope_recipient'), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), ) received_from = None received_with = 'POP3-SSL' @@ -402,6 +414,10 @@ ConfString(name='move_on_delete', required=False, default=None), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), # imaplib.IMAP4.login_cram_md5() requires the (unimplemented) # .authenticate(), so we can't do this yet (?). ConfBool(name='use_cram_md5', required=False, default=False), @@ -484,6 +500,10 @@ ConfString(name='move_on_delete', required=False, default=None), ConfFile(name='keyfile', required=False, default=None), ConfFile(name='certfile', required=False, default=None), + ConfFile(name='ca_certs', required=False, default=None), + ConfTupleOfStrings(name='ssl_fingerprints', required=False, default=()), + ConfString(name='ssl_version', required=False, default=None), + ConfString(name='ssl_ciphers', required=False, default=None), # imaplib.IMAP4.login_cram_md5() requires the (unimplemented) # .authenticate(), so we can't do this yet (?). ConfBool(name='use_cram_md5', required=False, default=False),
[-] [+]	Changed	getmail-4.46.0.tar.bz2/getmailcore/utilities.py ^
@@ -9,6 +9,10 @@ 'decode_crappy_text', 'format_header', 'check_ssl_key_and_cert', + 'check_ca_certs', + 'check_ssl_version', + 'check_ssl_fingerprints', + 'check_ssl_ciphers', 'deliver_maildir', 'eval_bool', 'expand_user_vars', @@ -39,6 +43,18 @@ import grp import getpass import commands +import sys + +# hashlib only present in python2.5, ssl in python2.6; used together +# in SSL functionality below +try: + import ssl +except ImportError: + ssl = None +try: + import hashlib +except ImportError: + hashlib = None # Optional gnome-keyring integration try: @@ -509,6 +525,83 @@ ) return (keyfile, certfile) +####################################### +def check_ca_certs(conf): + ca_certs = conf['ca_certs'] + if ca_certs is not None: + ca_certs = expand_user_vars(ca_certs) + if ssl is None: + raise getmailConfigurationError( + 'specifying ca_certs not supported by this installation of ' + 'Python; requires Python 2.6' + ) + if ca_certs and not os.path.isfile(ca_certs): + raise getmailConfigurationError( + 'optional ca_certs must be path to a valid file' + ) + return ca_certs + +####################################### +def check_ssl_version(conf): + ssl_version = conf['ssl_version'] + if ssl_version is None: + return None + if ssl is None: + raise getmailConfigurationError( + 'specifying ssl_version not supported by this installation of ' + 'Python; requires Python 2.6' + ) + ssl_version = ssl_version.lower() + if ssl_version == 'sslv23': + return ssl.PROTOCOL_SSLv23 + elif ssl_version == 'sslv3': + return ssl.PROTOCOL_SSLv3 + elif ssl_version == 'tlsv1': + return ssl.PROTOCOL_TLSv1 + elif ssl_version == 'tlsv1_1' and 'PROTOCOL_TLSv1_1' in dir(ssl): + return ssl.PROTOCOL_TLSv1_1 + elif ssl_version == 'tlsv1_2' and 'PROTOCOL_TLSv1_2' in dir(ssl): + return ssl.PROTOCOL_TLSv1_2 + else: + raise getmailConfigurationError( + 'unknown or unsupported ssl_version' + ) + +####################################### +def check_ssl_fingerprints(conf): + ssl_fingerprints = conf['ssl_fingerprints'] + if ssl_fingerprints is (): + return () + if ssl is None or hashlib is None: + raise getmailConfigurationError( + 'specifying ssl_fingerprints not supported by this installation of ' + 'Python; requires Python 2.6' + ) + + normalized_fprs = [] + for fpr in ssl_fingerprints: + fpr = fpr.lower().replace(':','') + if len(fpr) != 64: + raise getmailConfigurationError( + 'ssl_fingerprints must each be the SHA256 certificate hash in hex (with or without colons)' + ) + normalized_fprs.append(fpr) + return normalized_fprs + +####################################### +def check_ssl_ciphers(conf): + ssl_ciphers = conf['ssl_ciphers'] + if ssl_ciphers: + if sys.version_info < (2, 7, 0): + raise getmailConfigurationError( + 'specifying ssl_ciphers not supported by this installation of ' + 'Python; requires Python 2.7' + ) + if re.search(r'[^a-zA-z0-9, :!\-+@]', ssl_ciphers): + raise getmailConfigurationError( + 'invalid character in ssl_ciphers' + ) + return ssl_ciphers ####################################### keychain_password = None

Changes of Revision 27