Ubuntu Manpage: PullIMAP - Pull mails from an IMAP mailbox and deliver them to an SMTP session

Provided by: pullimap_0.5.6-1ubuntu1_all

NAME

       PullIMAP - Pull mails from an IMAP mailbox and deliver them to an SMTP session

SYNOPSIS

       pullimap [--config=FILE] [--idle[=SECONDS]] [--no-delivery] [--quiet] SECTION

DESCRIPTION

       pullimap  retrieves  messages from an IMAP mailbox and deliver them to an SMTP or LMTP transmission chan‐
       nel.  It can also remove old messages after a configurable retention period.

       A statefile is used to keep track of the mailbox’s UIDVALIDITY and UIDNEXT  values.   While  pullimap  is
       running,  the statefile is also used to keep track of UIDs being delivered, which avoids duplicate deliv‐
       eries in case the process is interrupted.  See the control flow section below for details.

OPTIONS

       --config=FILE
              Specify an alternate configuration file.  Relative paths start from $XDG_CONFIG_HOME/pullimap,  or
              ~/.config/pullimap if the XDG_CONFIG_HOME environment variable is unset.

       --idle[=seconds]
              Don’t  exit  after  a  successful poll.  Instead, keep the connection open and issue IDLE commands
              (require an IMAP server supporting RFC 2177) to watch for updates in the mailbox.  This  also  en‐
              ables  SO_KEEPALIVE on the socket.  Each IDLE command is terminated after at most seconds (29 min‐
              utes by default) to avoid being logged out for inactivity.

       --no-delivery
              Update the statefile, but skip SMTP/LMTP delivery.  This is mostly  useful  for  initializing  the
              statefile  when  migrating  to  pullimap from another similar program such as fetchmail(1) or get‐
              mail(1).

       -q, --quiet
              Try to be quiet.

       --debug
              Turn on debug mode.  Debug messages, which includes all IMAP traffic besides literals, are written
              to the given logfile.  The LOGIN and AUTHENTICATE commands are however redacted (in order to avoid
              disclosing authentication credentials) unless the --debug flag is set multiple times.

       -h, --help
              Output a brief help and exit.

       --version
              Show the version number and exit.

CONFIGURATION FILE

Unless told otherwise by the --config=FILE command-line option, pullimap reads its configuration from
$XDG_CONFIG_HOME/pullimap/config (or ~/.config/pullimap/config if the XDG_CONFIG_HOME environment vari‐
able is unset) as an INI file. The syntax of the configuration file is a series of OPTION=VALUE lines
organized under some [SECTION]; lines starting with a `#' or `;' character are ignored as comments.
Valid options are:

statefile
State file to use to keep track of the mailbox’s UIDVALIDITY and UIDNEXT values. Relative paths
start from $XDG_DATA_HOME/pullimap, or ~/.local/share/pullimap if the XDG_DATA_HOME environment
variable is unset. (Default: the parent section name of the option.)

mailbox
The IMAP mailbox (UTF-7 encoded and unquoted) to pull messages from. Support for persistent mes‐
sage Unique Identifiers (UID) is required. (Default: INBOX.)

deliver-method
PROTOCOL:[ADDRESS]:PORT where to deliver messages. Both SMTP and LMTP servers are supported, and
SMTP pipelining is used when possible. (Default: smtp:[127.0.0.1]:25.)

deliver-ehlo
Name to use in EHLO or LHLO commands. (Default: localhost.localdomain.)

deliver-rcpt
Message recipient. Note that the local part needs to quoted if it contains special characters;
see RFC 5321 for details. (Default: the username associated with the effective user ID of the
pullimap process.)

purge-after
Retention period (in days), after which messages are removed from the IMAP server. (The value is
at best 24h accurate due to the IMAP SEARCH criterion ignoring time and timezone.) If purge-after
is set to 0 then messages are deleted immediately after delivery. Otherwise pullimap issues an
IMAP SEARCH (or extended SEARCH on servers advertising the ESEARCH capability) command to list old
messages; if --idle is set then the SEARCH command is issued again every 12 hours.

type One of imap, imaps or tunnel. type=imap and type=imaps are respectively used for IMAP and IMAP
over SSL/TLS connections over an INET socket. type=tunnel causes pullimap to create an unnamed
pair of connected sockets for inter-process communication with a command instead of opening a net‐
work socket. (Default: imaps.)

host Server hostname or IP address, for type=imap and type=imaps. The value can optionally be enclosed
in square brackets to force its interpretation as an IP literal (hence skip name resolution).
(Default: localhost.)

port Server port. (Default: 143 for type=imap, 993 for type=imaps.)

proxy Optional SOCKS proxy to use for TCP connections to the IMAP server (type=imap and type=imaps on‐
ly), formatted as PROTOCOL://[USER:PASSWORD@]PROXYHOST[:PROXYPORT]. If PROXYPORT is omitted, it
is assumed at port 1080. Only SOCKSv5 is supported (with optional username/password authentica‐
tion), in two flavors: socks5:// to resolve hostname locally, and socks5h:// to let the proxy re‐
solve hostname.

command
Command to use for type=tunnel. Must speak the IMAP4rev1 protocol on its standard output, and un‐
derstand it on its standard input. The value is passed to `/bin/sh -c` if it contains shell
metacharacters; otherwise it is split into words and the resulting list is passed to execvp(3).

STARTTLS
Whether to use the STARTTLS directive to upgrade to a secure connection. Setting this to YES for
a server not advertising the STARTTLS capability causes pullimap to immediately abort the connec‐
tion. (Ignored for types other than imap. Default: YES.)

auth Space-separated list of preferred authentication mechanisms. pullimap uses the first mechanism in
that list that is also advertised (prefixed with AUTH=) in the server’s capability list. Support‐
ed authentication mechanisms are PLAIN and LOGIN. (Default: PLAIN LOGIN.)

username, password
Username and password to authenticate with. Can be required for non pre-authenticated connec‐
tions, depending on the chosen authentication mechanism.

compress
Whether to use the IMAP COMPRESS extension for servers advertising it. (Default: YES.)

null-stderr
Whether to redirect command’s standard error to /dev/null for type=tunnel. (Default: NO.)

SSL_protocols
Space-separated list of SSL/TLS protocol versions to explicitly enable (or disable if prefixed
with an exclamation mark !). Potentially known protocols are SSLv2, SSLv3, TLSv1, TLSv1.1,
TLSv1.2, and TLSv1.3, depending on the OpenSSL version used. Enabling a protocol is a short-hand
for disabling all other protocols.

DEPRECATED: Use SSL_protocol_min and/or SSL_protocol_max instead.

SSL_protocol_min, SSL_protocol_max
Set minimum resp. maximum SSL/TLS protocol version to use for the connection. Potentially recog‐
nized values are SSLv3, TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3, depending on the OpenSSL version
used.

SSL_cipherlist, SSL_ciphersuites
Sets the TLSv1.2 and below cipher list resp. TLSv1.3 cipher suites. The combination of these
lists is sent to the server, which then determines which cipher to use (normally the first sup‐
ported one from the list sent by the client). The default suites depend on the OpenSSL version
and its configuration, see ciphers(1ssl) for more information.

SSL_fingerprint
Space-separated list of acceptable fingerprints for the server certificate’s Subject Public Key
Info, in the form [ALGO$]DIGEST_HEX where ALGO is the digest algorithm (by default sha256). At‐
tempting to connect to a server with a non-matching certificate SPKI fingerprint causes pullimap
to abort the connection during the SSL/TLS handshake. The following command can be used to com‐
pute the SHA-256 digest of a certificate’s Subject Public Key Info:

$ openssl x509 -in /path/to/server/certificate.pem -pubkey \
| openssl pkey -pubin -outform DER \
| openssl dgst -sha256

Specifying multiple digest values can be useful in key rollover scenarios and/or when the server
supports certificates of different types (for instance a dual-cert RSA/ECDSA setup). In that case
the connection is aborted when none of the specified digests matches.

SSL_verify
Whether to 1/ verify the server certificate chain; and 2/ match its Subject Alternative Name (SAN)
or Subject CommonName (CN) against the value of the host option. (Default: YES.)

Note that using SSL_fingerprint to specify the fingerprint of the server certificate provides an
independent server authentication measure as it pins directly its key material and ignore its
chain of trust.

SSL_CAfile
File containing trusted certificates to use during server certificate verification when SSL_veri‐
fy=YES.

Trusted CA certificates are loaded from the default system locations unless one (or both) of
SSL_CAfile or SSL_CApath is set.

SSL_CApath
Directory to use for server certificate verification when SSL_verify=YES. This directory must be
in “hash format”, see verify(1ssl) for more information.

Trusted CA certificates are loaded from the default system locations unless one (or both) of
SSL_CAfile or SSL_CApath is set.

SSL_hostname
Name to use for the TLS SNI (Server Name Indication) extension. The default value is taken from
the host option when it is a hostname, and to the empty string when it is an IP literal. Setting
SSL_hostname to the empty string explicitly disables SNI.

CONTROL FLOW

pullimap opens the statefile corresponding to a given configuration SECTION with O_DSYNC to ensure that
written data is flushed to the underlying hardware by the time write(2) returns. Moreover an exclusive
lock is placed on the file descriptor immediately after opening to prevent multiple pullimap processes
from accessing the statefile concurrently.

Each statefile consists of a series of 32-bits big-endian integers. Usually there are only two integers:
the first is the mailbox’s UIDVALIDITY value, and the second is the mailbox’s last seen UIDNEXT value
(pullimap then assumes that all messages with UID smaller than this UIDNEXT value have already been re‐
trieved and delivered). The IMAP4rev1 specification does not guaranty that untagged FETCH responses are
sent ordered by UID in response to a UID FETCH command. Thus it would be unsafe for pullimap to update
the UIDNEXT value in its statefile while the UID FETCH command is progress. Instead, for each untagged
FETCH response received while the UID FETCH command is in progress, pullimap delivers the message RFC822
body to the SMTP or LMTP server (specified with deliver-method) then appends the message UID to the
statefile. When the UID FETCH command eventually terminates, pullimap updates the UIDNEXT value in the
statefile and truncate the file down to 8 bytes. Keeping track of message UIDs as they are received
avoids duplicate in the event of a crash or connection loss while the UID FETCH command is in progress.

In more details, pullimap works as follows:

1. Issue a UID FETCH command to retrieve message ENVELOPE and RFC822 (and UID) with UID bigger or equal
than the UIDNEXT value found in the statefile. While the UID FETCH command is in progress, perform
the following for each untagged FETCH response sent by the server:

i. if no SMTP/LMTP transmission channel was opened, open one to the server specified with deliver-
method and send an EHLO (or LHO) command with the domain specified by deliver-ehlo (the channel
is kept open and shared for all messages retrieved while the UID FETCH IMAP command is in
progress);

ii. perform a mail transaction (using SMTP pipelining if possible) to deliver the retrieved message
RFC822 body to the SMTP or LMTP session; and

iii. append the message UID to the statefile.

2. If an SMTP/LMTP transmission channel was opened, send a QUIT command to terminate it gracefully.

3. Issue a UID STORE command to mark all retrieved messages (and stalled UIDs found in the statefile af‐
ter the eighth byte) as \Seen.

4. Update the statefile with the new UIDNEXT value (bytes 5-8).

5. Truncate the statefile down to 8 bytes (so that it contains only two 32-bits integers, respectively
the mailbox’s current UIDVALIDITY and UIDNEXT values).

6. If --idle was set, issue an IDLE command; stop idling and go back to step 1 when a new message is re‐
ceived (or when the IDLE timeout expires).

STANDARDS

       • M.  Leech, M.  Ganis, Y.  Lee, R.  Kuris, D.  Koblas and L.  Jones, SOCKS Protocol Version 5, RFC 1928,
         March 1996.

       • M.  Leech, Username/Password Authentication for SOCKS V5, RFC 1929, March 1996.

       • J.  Myers, Local Mail Transfer Protocol, RFC 2033, October 1996.

       • J.  Myers, IMAP4 non-synchronizing literals, RFC 2088, January 1997.

       • D.  Goldsmith and M.  Davis, A Mail-Safe Transformation Format of Unicode, RFC 2152, May 1997.

       • B.  Leiba, IMAP4 IDLE command, RFC 2177, June 1997.

       • C.  Newman, Using TLS with IMAP, POP3 and ACAP, RFC 2595, June 1999.

       • N.  Freed, SMTP Service Extension for Command Pipelining, RFC 2920, September 2000.

       • M.  Crispin, Internet Message Access Protocol - Version 4rev1, RFC 3501, March 2003.

       • M.  Crispin, Internet Message Access Protocol (IMAP) - UIDPLUS extension, RFC 4315, December 2005.

       • A.  Gulbrandsen, The IMAP COMPRESS Extension, RFC 4978, August 2007.

       • A.   Melnikov and D.  Cridland, IMAP4 Extension to SEARCH Command for Controlling What Kind of Informa‐
         tion Is Returned, RFC 4731, November 2006.

       • R.  Siemborski and A.  Gulbrandsen, IMAP Extension for Simple Authentication and Security Layer  (SASL)
         Initial Client Response, RFC 4959, September 2007.

       • J.  Klensin, Simple Mail Transfer Protocol, RFC 5321, October 2008.

BUGS AND FEEDBACK

       Bugs  or  feature  requests  for  pullimap  should  be  filed  with  the  Debian project’s bug tracker at
       <https://www.debian.org/Bugs/>.

AUTHORS

       Guilhem Moulin (mailto:guilhem@fripost.org).

                                                   March 2016                                        pullimap(1)