|
[-]
[+]
|
Changed |
getmail.changes
|
|
|
|
[-]
[+]
|
Changed |
getmail.spec
^
|
|
|
|
[-]
[+]
|
Changed |
getmail-4.42.0.tar.bz2/PKG-INFO
^
|
| @@ -1,6 +1,6 @@
-Metadata-Version: 1.0
+Metadata-Version: 1.1
Name: getmail
-Version: 4.41.0
+Version: 4.42.0
Summary: a mail retrieval, sorting, and delivering system
Home-page: http://pyropus.ca/software/getmail/
Author: Charles Cazabon
|
|
[-]
[+]
|
Changed |
getmail-4.42.0.tar.bz2/docs/CHANGELOG
^
|
| @@ -1,3 +1,8 @@
+Version 4.42.0
+3 August 2013
+ -fix problem with non-ascii characters in newly-added message header fields
+ with output from Filter_classifier. Thanks: "Gour".
+
Version 4.41.0
26 May 2013
-messages retrieved with POP could have a blank trailing line removed when
|
|
[-]
[+]
|
Deleted |
getmail-4.42.0.tar.bz2/docs/configuration.txt
^
|
| @@ -1,1497 +0,0 @@
- Link: Charles Cazabon's Software (Contents Up Index)
-
- 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.
-
- 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.
-
- 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.
-
- 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.
- * keyfile (string) -- use the specified PEM-formatted key file in the
- SSL negotiation. Note that no certificate or key validation is done.
- * certfile (string) -- use the specified PEM-formatted certificate file
- in the SSL negotiation. Note that no certificate or key validation is
- done.
-
- 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 SimplePOP3SSLRetriever for definition.
- * certfile (string) -- see SimplePOP3SSLRetriever 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 SimplePOP3SSLRetriever for definition.
- * certfile (string) -- see SimplePOP3SSLRetriever 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 SimplePOP3SSLRetriever for definition.
- * certfile (string) -- see SimplePOP3SSLRetriever 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 SimplePOP3SSLRetriever for definition.
- * certfile (string) -- see SimplePOP3SSLRetriever 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=%(recipient))
- 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(TM), 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/plain,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
-
- 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 getmailrc-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.
|
|
[-]
[+]
|
Deleted |
getmail-4.42.0.tar.bz2/docs/documentation.txt
^
|
| @@ -1,427 +0,0 @@
- Link: Charles Cazabon's Software (Contents Up Index)
-
- 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. <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.
-
-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:
-
- * POP3
- * POP3-over-SSL
- * IMAP4
- * IMAP4-over-SSL
- * 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.
|
|
[-]
[+]
|
Deleted |
getmail-4.42.0.tar.bz2/docs/faq.txt
^
|
| @@ -1,1051 +0,0 @@
- Link: Charles Cazabon's Software (Contents Up Index)
-
- 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.
-
- 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 will 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.
|
|
[-]
[+]
|
Deleted |
getmail-4.42.0.tar.bz2/docs/troubleshooting.txt
^
|
| @@ -1,270 +0,0 @@
- Link: Charles Cazabon's Software (Contents Up Index)
-
- 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.42.0.tar.bz2/getmail.spec
^
|
| @@ -2,7 +2,7 @@
Summary: POP3 mail retriever with reliable Maildir delivery
Name: getmail
-Version: 4.41.0
+Version: 4.42.0
Release: 1
License: GPL
Group: Applications/Internet
@@ -52,6 +52,21 @@
%{python_sitelib}/getmailcore/
%changelog
+* Sat Aug 03 2013 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca>
+-update to version 4.42.0
+
+* Sat Aug 03 2013 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca>
+-update to version 4.42.0
+
+* Sat Aug 03 2013 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca>
+-update to version 4.42.0
+
+* Sat Aug 03 2013 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca>
+-update to version 4.42.0
+
+* Sat Aug 03 2013 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca>
+-update to version 4.42.0
+
* Sun May 26 2013 Charles Cazabon <charlesc-getmail-rpm@pyropus.ca>
-update to version 4.41.0
|
|
[-]
[+]
|
Changed |
getmail-4.42.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.41.0'
+__version__ = '4.42.0'
__all__ = [
'baseclasses',
|
|
[-]
[+]
|
Changed |
getmail-4.42.0.tar.bz2/getmailcore/filters.py
^
|
| @@ -343,6 +343,11 @@
for line in [line.strip() for line in stdout.readlines()
if line.strip()]:
+ # Output from filter can be in any random text encoding and may
+ # not even be valid, which causes problems when trying to stick
+ # that text into message headers. Try to decode it to something
+ # sane here first.
+ line = decode_crappy_text(line)
msg.add_header('X-getmail-filter-classifier', line)
return (exitcode, msg, err)
|
|
[-]
[+]
|
Changed |
getmail-4.42.0.tar.bz2/getmailcore/message.py
^
|
| @@ -204,7 +204,7 @@
include_from)
def add_header(self, name, content):
- self.__msg[name] = Header(content.rstrip())
+ self.__msg[name] = Header(content.rstrip(), 'utf-8')
def remove_header(self, name):
del self.__msg[name]
|
|
[-]
[+]
|
Changed |
getmail-4.42.0.tar.bz2/getmailcore/utilities.py
^
|
| @@ -6,6 +6,8 @@
'address_no_brackets',
'change_usergroup',
'change_uidgid',
+ 'decode_crappy_text',
+ 'format_header',
'check_ssl_key_and_cert',
'deliver_maildir',
'eval_bool',
@@ -420,6 +422,29 @@
% (uid, gid, o))
#######################################
+def decode_crappy_text(s):
+ '''Take a line of text in arbitrary and possibly broken bytestring encoding
+ and return an ASCII or unicode version of it.
+ '''
+ # first, assume it was written in the encoding of the user's terminal
+ lang = os.environ.get('LANG')
+ if lang:
+ try:
+ (lang, encoding) = lang.split('.')
+ return s.decode(encoding)
+ except (UnicodeError, ValueError), o:
+ pass
+ # that failed; try well-formed in various common encodings next
+ for encoding in ('ascii', 'utf-8', 'latin-1', 'utf-16'):
+ try:
+ return s.decode(encoding)
+ except UnicodeError, o:
+ continue
+ # all failed - force it
+ return s.decode('utf-8', 'replace')
+
+
+#######################################
def format_header(name, line):
'''Take a long line and return rfc822-style multiline header.
'''
|
