diff options
| -rw-r--r-- | Changelog | 2 | ||||
| -rw-r--r-- | pullimap.1 | 236 | ||||
| -rw-r--r-- | pullimap.sample | 32 |
3 files changed, 270 insertions, 0 deletions
@@ -4,6 +4,8 @@ interimap (0.3) upstream; * Add an option 'SSL_protocols' to list SSL protocols to enable or disable. The default value, "!SSLv2 !SSLv3", enables only TLSv1 and above. + * New script 'pullimap', to pull mails from an IMAP mailbox and + deliver them to a SMTP session. -- Guilhem Moulin <guilhem@guilhem.org> Mon, 28 Sep 2015 01:16:47 +0200 diff --git a/pullimap.1 b/pullimap.1 new file mode 100644 index 0000000..e0f1ec3 --- /dev/null +++ b/pullimap.1 @@ -0,0 +1,236 @@ +.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 retrives messages from an IMAP mailbox and deliver them +to a SMTP or LMTP transmission channel. +It can also remove delivered 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. +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 serie 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 LHO commands. +(Default: \(lq\fIlocalhost.localdomain\fR\)\(rq.) + + +.TP +.I deliver\-rcpt +Message recpient. +(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.) + +.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 +advertizing 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 . diff --git a/pullimap.sample b/pullimap.sample new file mode 100644 index 0000000..63ff9de --- /dev/null +++ b/pullimap.sample @@ -0,0 +1,32 @@ +mailbox = INBOX +deliver-method = smtp:[127.0.0.1]:25 +#deliver-method = smtp:[127.0.0.1]:10024 +purge-after = 90 + +# SSL options +SSL_CApath = /etc/ssl/certs +#SSL_verify = YES +#SSL_protocols = !SSLv2 !SSLv3 !TLSv1 !TLSv1.1 +#SSL_cipherlist = EECDH+AESGCM:!MEDIUM:!LOW:!EXP:!aNULL:!eNULL + +[private] +#type = imaps +host = imap.guilhem.org +#port = 993 +#proxy = socks5h://localhost:9050 +username = guilhem +password = xxxxxxxxxxxxxxxx +#compress = YES +#SSL_fingerprint = sha256$62E436BB329C46A628314C49BDA7C2A2E86C57B2021B9A964B8FABB6540D3605 + +[work] +#type = imaps +host = imap.example.com +#port = 993 +#proxy = socks5h://localhost:9050 +username = guilhem +password = xxxxxxxxxxxxxxxx +#compress = YES +#SSL_fingerprint = sha256$c93677ac6a4ac7d0a2b412c1bfdd83b9191c853aa8685bf5440f154e647caacf + +# vim:ft=dosini |