path: root/pullimap.1

.TH PULLIMAP "1" "MARCH 2016" "PullIMAP" "User Commands"

.SH NAME
PullIMAP \- Pull mails from an IMAP mailbox and deliver them to a SMTP session

.SH SYNOPSIS
.B pullimap\fR [\fB--config=\fIFILE\fR] [\fB--idle\fR[\fB=\fISECONDS\fR]]
[\fB--no-delivery\fR] [\fB--quiet\fR] \fISECTION\fR


.SH DESCRIPTION
.PP
.B PullIMAP\fR retrieves messages from an IMAP mailbox and deliver them
to a SMTP or LMTP transmission channel.
It can also remove old messages after a configurable retention period.

.PP
A \fIstatefile\fR is used to keep track of the mailbox's UIDVALIDITY and
UIDNEXT values.  While \fBPullIMAP\fR is running, the \fIstatefile\fR is
also used to keep track of UIDs being delivered, which avoids duplicate
deliveries if the process is interrupted.
See the \fBCONTROL FLOW\fR section below.

.SH OPTIONS
.TP
.B \-\-config=\fR\fIFILE\fR
Specify an alternate configuration file.  Relative paths start from
\fI$XDG_CONFIG_HOME\fR, or \fI~/.config\fR if the XDG_CONFIG_HOME
environment variable is unset.

.TP
.B \fB\-\-idle\fR[\fB=\fR\fIseconds\fR]
Don't exit after a successful poll; instead, keep the connection open
and issue IDLE commands (requires an IMAP server supporting RFC 2177) to
watch for updates in the mailbox.
This also sets SO_KEEPALIVE on the socket.
Each IDLE is terminated after at most \fIseconds\fR (29 minutes by
default) to avoid being logged out for inactivity.

.TP
.B \fB\-\-no\-delivery
Update the \fIstatefile\fR, but skip SMTP/LMTP delivery.  This is mostly
useful for initializing the \fIstatefile\fR when migrating to
\fBPullIMAP\fR from another equivalent program such as \fIgetmail\fR(1)
or \fIfetchmail\fR(1).

.TP
.B \-q\fR, \fB\-\-quiet\fR
Try to be quiet.

.TP
.B \-\-debug
Turn on debug mode.  Debug messages are written to the error output.
Note that this include all IMAP traffic (except literals).  Depending on
the chosen authentication mechanism, this might include authentication
credentials.

.TP
.B \-h\fR, \fB\-\-help\fR
Output a brief help and exit.

.TP
.B \-\-version
Show the version number and exit.

.SH CONFIGURATION FILE

Unless told otherwise by the \fB\-\-config=\fR\fIFILE\fR option,
\fBPullIMAP\fR reads its configuration from
\fI$XDG_CONFIG_HOME/pullimap\fR (or \fI~/.config/pullimap\fR if the
XDG_CONFIG_HOME environment variable is unset) as an INI file.
The syntax of the configuration file is a series of
\fIOPTION\fR=\fIVALUE\fR lines organized under some \fI[SECTION]\fR;
lines starting with a \(oq#\(cq or \(oq;\(cq character are ignored as
comments.
Valid options are:

.TP
.I statefile
State file to use to keep track of the \fImailbox\fR's UIDVALIDITY and
UIDNEXT values.
Relative paths start from \fI$XDG_DATA_HOME/pullimap\fR, or
\fI~/.local/share/pullimap\fR if the XDG_DATA_HOME environment variable
is unset.
(Default: \(lq\fISECTION\fR\)\(rq, where \fISECTION\fR is the section
name of the option.)

.TP
.I mailbox
The IMAP mailbox to pull messages from.
Support for persistent message Unique Identifiers (UID) is required.
(Default: \(lqINBOX\)\(rq.)

.TP
.I deliver\-method
\fR\fIprotocol\fR:\fI[address]\fI\fR:\fIport\fR where to deliver
messages.  Both SMTP [RFC 5321] and LMTP [RFC 2030] are supported.
(Default: \(lqsmtp:[127.0.0.1]:25\)\(rq.)

.TP
.I deliver\-ehlo
Hostname to use in EHLO or LHLO commands.
(Default: \(lq\fIlocalhost.localdomain\fR\)\(rq.)


.TP
.I deliver\-rcpt
Message recipient.
(Default: the username associated with the effective uid of the
\fBpullimap\fR process.)

.TP
.I purge\-after
Retention period (in days), after which messages are removed from the
IMAP server.  (The value is at best 24h accurate due to IMAP SEARCH
criterion ignoring time and timezone.)
If \fIpurge\-after\fR is set to \(lq0\(rq then messages are deleted
immediately after delivery.  Otherwise \fBPullIMAP\fR issues an IMAP
SEARCH command to list old messages; if \fB\-\-idle\fR is set then the
SEARCH command is issued again every 12 hours.

.TP
.I type
One of \(lqimap\(rq, \(lqimaps\(rq or \(lqtunnel\(rq.
\fItype\fR=imap and \fItype\fR=imaps are respectively used for IMAP and
IMAP over SSL/TLS connections over a INET socket.
\fItype\fR=tunnel causes \fBPullIMAP\fR to open a pipe to a
\fIcommand\fR instead of a raw socket.
Note that specifying \fItype\fR=tunnel in the \(lq[remote]\(rq section
makes the default \fIdatabase\fR to be \(lqlocalhost.db\(rq.
(Default: \(lqimaps\(rq.)

.TP
.I host
Server hostname, for \fItype\fR=imap and \fItype\fR=imaps.
(Default: \(lqlocalhost\(rq.)

.TP
.I port
Server port.
(Default: \(lq143\(rq for \fItype\fR=imap, \(lq993\(rq for
\fItype\fR=imaps.)

.TP
.I proxy
An optional SOCKS proxy to use for TCP connections to the IMAP server
(\fItype\fR=imap and \fItype\fR=imaps only), formatted as
\(lq\fIprotocol\fR://[\fIuser\fR:\fIpassword\fR@]\fIproxyhost\fR[:\fIproxyport\fR]\(rq.
If \fIproxyport\fR is omitted, it is assumed at port 1080.
Only SOCKSv5 is supported, in two flavors: \(lqsocks5://\(rq to resolve
\fIhostname\fR locally, and \(lqsocks5h://\(rq to let the proxy resolve
\fIhostname\fR.

.TP
.I command
Command to use for \fItype\fR=tunnel.  Must speak the IMAP4rev1 protocol
on its standard output, and understand it on its standard input.

.TP
.I STARTTLS
Whether to use the \(lqSTARTTLS\(rq directive to upgrade to a secure
connection.  Setting this to \(lqYES\(rq for a server not advertising
the \(lqSTARTTLS\(rq capability causes \fBPullIMAP\fR to immediately
abort the connection.
(Ignored for \fItype\fRs other than \(lqimap\(rq.  Default: \(lqYES\(rq.)

.TP
.I auth
Space\-separated list of preferred authentication mechanisms.
\fBPullIMAP\fR uses the first mechanism in that list that is also
advertised (prefixed with \(lqAUTH=\(rq) in the server's capability list.
Supported authentication mechanisms are \(lqPLAIN\(rq and \(lqLOGIN\(rq.
(Default: \(lqPLAIN LOGIN\(rq.)

.TP
.I username\fR, \fIpassword\fR
Username and password to authenticate with.  Can be required for non
pre\-authenticated connections, depending on the chosen authentication
mechanism.

.TP
.I compress
Whether to use the IMAP COMPRESS extension [RFC4978] for servers
advertising it.
(Default: \(lqYES\(rq.)

.TP
.I null\-stderr
Whether to redirect \fIcommand\fR's standard error to \(lq/dev/null\(rq
for type \fItype\fR=tunnel.
(Default: \(lqNO\(rq.)

.TP
.I SSL_protocols
A space-separated list of SSL protocols to enable or disable (if
prefixed with an exclamation mark \(oq!\(cq).  Known protocols are
\(lqSSLv2\(rq, \(lqSSLv3\(rq, \(lqTLSv1\(rq, \(lqTLSv1.1\(rq, and
\(lqTLSv1.2\(rq.  Enabling a protocol is a short-hand for disabling all
other protocols.
(Default: \(lq!SSLv2 !SSLv3\(rq, i.e., only enable TLSv1 and above.)

.TP
.I SSL_cipher_list
The cipher list to send to the server.  Although the server determines
which cipher suite is used, it should take the first supported cipher in
the list sent by the client.  See \fBciphers\fR(1ssl) for more
information.

.TP
.I SSL_fingerprint
Fingerprint of the server certificate (or its public key) in the form
\fIALGO\fR$\fIDIGEST_HEX\fR, where \fIALGO\fR is the used algorithm
(default \(lqsha256\(rq).
Attempting to connect to a server with a non-matching certificate
fingerprint causes \fBPullIMAP\fR to abort the connection during the
SSL/TLS handshake.

.TP
.I SSL_verify
Whether to verify the server certificate chain.
Note that using \fISSL_fingerprint\fR to specify the fingerprint of the
server certificate is an orthogonal authentication measure as it ignores
the CA chain.
(Default: \(lqYES\(rq.)

.TP
.I SSL_CApath
Directory to use for server certificate verification if
\(lq\fISSL_verify\fR=YES\(rq.
This directory must be in \(lqhash format\(rq, see \fBverify\fR(1ssl)
for more information.

.TP
.I SSL_CAfile
File containing trusted certificates to use during server certificate
authentication if \(lq\fISSL_verify\fR=YES\(rq.

.SH CONTROL FLOW
\fBPullIMAP\fR opens the \fIstatefile\fR corresponding to a given
configuration \fISECTION\fR with O_DSYNC to ensure that written data is
flushed to the underlying hardware by the time \fIwrite\fR(2) returns.
Moreover an exclusive lock is placed on the file descriptor immediately
after opening to prevent multiple \fBpullimap\fR processes from
accessing the \fIstatefile\fR concurrently.

Each \fIstatefile\fR consists of a series of 32-bits big-endian
integers.  Usually there are only two integers:
the first is the \fImailbox\fR's UIDVALIDITY value, and the second is
the \fImailbox\fR's last seen UIDNEXT value (\fBPullIMAP\fR then assumes
that all messages with UID smaller than this UIDNEXT value have already
been retrieved and delivered).
The IMAP4rev1 specification [RFC 3501] does not guaranty that untagged
FETCH responses are sent ordered by UID in response of an UID FETCH
command.  Thus it would be unsafe for \fBPullIMAP\fR to update the
UIDNEXT value in the \fIstatefile\fR while the UID FETCH command is
progress.
Instead, for each untagged FETCH response received while while the UID
FETCH command is in progress, \fBPullIMAP\fR delivers the message BODY
to the SMTP or LMTP server specified with \fIdeliver\-method\fR then
appends the message UID to the \fIstatefile\fR.  When the UID FETCH
command eventually terminates, \fBPullIMAP\fR updates the UIDNEXT value
in the \fIstatefile\fR and truncate the file down to 8 bytes.
Keeping track of message UIDs as they are received avoids duplicate in
the even of a crash or session loss while the UID FETCH command is in
progress.

In more details, \fBPullIMAP\fR works as follows:

.nr step 1 1
.IP \n[step]. 4
Issue an UID FETCH command to retrieve message ENVELOPE and BODY (and
UID) with UID bigger or equal than the UIDNEXT value found in the
\fIstatefile\fR.
While the UID FETCH command is in progress, perform the following
for each untagged FETCH response sent by the server:
.RS
\(bu
if no SMTP/LMTP transmission channel was opened, open one to the server
specified with \fIdeliver\-method\fR and send an EHLO (or LHO) command
with the domain given by \fIdeliver\-ehlo\fR;
.br
\(bu
perform a mail transaction (using SMTP pipelining [RFC 2920] if
possible) to send the retrieved message BODY to the SMTP or LMTP
session; and
.br
\(bu
append the message UID to the \fIstatefile\fR.
.RE

.IP \n+[step].
If a SMTP/LMTP transmission channel was opened, send a QUIT command to
close it gracefully.

.IP \n+[step].
Issue an UID STORE command to mark all retrieved messages (and stalled
UIDs found in the \fIstatefile\fR after the UIDNEXT value) as \\Seen.

.IP \n+[step].
Update the \fIstatefile\fR with the new UIDNEXT value.

.IP \n+[step].
Truncate the \fIstatefile\fR down to 8 bytes (so that it contains only
two 32-bits integers, respectively the \fImailbox\fR's UIDVALIDITY and
UIDNEXT values).

.IP \n+[step].
If \fB\-\-idle\fR was set, issue an IDLE command; stop idling and go
back to step 1. whenever a new message is received.

.SH AUTHOR
.ie \n[www-html] \{\
  Written by
. MTO guilhem@fripost.org "Guilhem Moulin" .
\}
.el \{\
  Written by Guilhem Moulin
. MT guilhem@fripost.org
. ME .
\}