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 statefile is used to keep track of the mailbox's UIDVALIDITY and
UIDNEXT values.  While \fBPullIMAP\fR is running, the statefile is also
used to keep track of UIDs being delivered, which avoids duplicate
deliveries if the process is interrupted.

.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 state file, but skip SMTP/LMTP delivery.  This is mostly
useful for initializing the statefile 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 AUTHOR
Written by Guilhem Moulin
.MT guilhem@fripost.org
.ME .