aboutsummaryrefslogtreecommitdiffstats
path: root/pullimap.1
blob: 52a6152b53e101494122d669547f188be7680e7b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
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 retrieves 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 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.)

.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 .