From c5468b4a598afa09d8e4c0d8e46ab44cca1e9c60 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 9 Mar 2016 15:04:20 +0100 Subject: pullimap: purge old messages every 12h. --- pullimap.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pullimap.1') diff --git a/pullimap.1 b/pullimap.1 index 57a4adf..d4ef502 100644 --- a/pullimap.1 +++ b/pullimap.1 @@ -116,7 +116,7 @@ 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 6 hours. +SEARCH command is issued again every 12 hours. .TP .I type -- cgit v1.2.3 From 50f79472babc840807bcb183aaab7ddbd9ebfa71 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 9 Mar 2016 17:18:07 +0100 Subject: pullimap: add control flow details in the manpage. --- pullimap.1 | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 80 insertions(+), 7 deletions(-) (limited to 'pullimap.1') diff --git a/pullimap.1 b/pullimap.1 index d4ef502..8f27d85 100644 --- a/pullimap.1 +++ b/pullimap.1 @@ -15,10 +15,11 @@ 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 +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 @@ -38,10 +39,10 @@ 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). +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 @@ -234,6 +235,78 @@ for more information. 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 +.nr step 1 1 +.IP \n[step]. 4 +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; +.IP \n+[step]. +perform a mail transaction (using SMTP pipelining [RFC 2920] if +possible) to send the retrieved message BODY to the SMTP or LMTP +session; and +.IP \n+[step]. +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 Written by Guilhem Moulin .MT guilhem@fripost.org -- cgit v1.2.3 From 04a259a845a1c9eb9c99db41cd940c89f0bc68e9 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 9 Mar 2016 20:12:03 +0100 Subject: Improve mailto: link for groff_www. --- pullimap.1 | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'pullimap.1') diff --git a/pullimap.1 b/pullimap.1 index 8f27d85..342afce 100644 --- a/pullimap.1 +++ b/pullimap.1 @@ -308,6 +308,12 @@ 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 -Written by Guilhem Moulin -.MT guilhem@fripost.org -.ME . +.ie \n[www-html] \{\ + Written by +. MTO guilhem@fripost.org "Guilhem Moulin" . +\} +.el \{\ + Written by Guilhem Moulin +. MT guilhem@fripost.org +. ME . +\} -- cgit v1.2.3 From a657c564c46338bb360690661152cf4a25fe8927 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 9 Mar 2016 20:28:31 +0100 Subject: pullimap.1: Work around groff_www rendering bug with nested lists. --- pullimap.1 | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'pullimap.1') diff --git a/pullimap.1 b/pullimap.1 index 342afce..2d92e9d 100644 --- a/pullimap.1 +++ b/pullimap.1 @@ -274,20 +274,21 @@ UID) with UID bigger or equal than the UIDNEXT value found in the While the UID FETCH command is in progress, perform the following for each untagged FETCH response sent by the server: .RS -.nr step 1 1 -.IP \n[step]. 4 +\(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; -.IP \n+[step]. +.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 -.IP \n+[step]. +.br +\(bu append the message UID to the \fIstatefile\fR. .RE -.IP \n-[step]. +.IP \n+[step]. If a SMTP/LMTP transmission channel was opened, send a QUIT command to close it gracefully. -- cgit v1.2.3