pullimap: add a manpage and a configuration file.

1 files changed, 236 insertions, 0 deletions

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 .