95.1.38. pepsi-stage-quarantine¶
hold a message until an operator releases or deletes it
- Manual section:
1
95.1.38.1.1. Name¶
pepsi-stage-quarantine - the quarantine stage of the Pepsi pipeline.
95.1.38.1.2. Synopsis¶
pepsi-stage-quarantine [GLOBAL-OPTIONS] worker
95.1.38.1.3. Description¶
pepsi-stage-quarantine is a stage program run by pepsi-dispatch(1)
as a persistent worker reading message ids on standard input. It holds every
message that reaches it until an operator releases or deletes it with
pepsi-queue(1) quarantine. Mail reaches it wherever the pipeline
routes mail to it: a milter’s quarantine request (the QUARANTINE_STAGE of
pepsi-stage-milter(1), or of a pre-queue milter of
pepsi-ingress(1)), pepsi-stage-decrypt(1)’s QUARANTINE_STAGE, or
any other stage’s route.
The stage sees a message at most three times:
On arrival it records
state.quarantine.sinceand leaves the rowpaused. Without MAX_HOLD the row has notimeout, so pepsi-dispatch(1) never wakes it on its own; the message waits until someone acts. With MAX_HOLD thetimeoutis the end of the hold, andstate.quarantine.untilrecords it.On release (
pepsi-queue quarantine release, or an operator’spepsi-queue set-stageor administrative requeue to this stage) the row comes back to this stage aspending. The stage recordsreleased_atand sends the message on to RELEASE_STAGE. ThePOST /resumewebhook of pepsi-httpd(1), which resumes a message once a payment arrives, leaves a held message alone: its token is a payment notification, not an operator’s decision.On expiry, when the dispatcher wakes the row at the end of MAX_HOLD, the stage records
expiredand routes the message to EXPIRE_STAGE, or deletes it when that is not set.
A release and an expiry look the same to the stage, so it tells them apart by
its clock: a claim at or after until is the expiry. A small allowance of up
to five seconds, and at most half the hold, covers a clock difference between
the database host and this one; a release in that last moment therefore counts
as an expiry, never the other way round. MAX_HOLD is read when a hold
begins: changing it later changes neither the end of a hold already recorded
nor whether that hold ends at all.
A message on its way to EXPIRE_STAGE is marked the way pepsi-queue(1)
gc marks an expired quarantine: state.failed_stage is this stage,
state.failure_class is quarantine-expired, a RET=FULL that the
sender asked for becomes RET=HDRS, and a carried state.bounce is
dropped, so that pepsi-stage-bounce(1) can tell the sender that the
message was held and not released without returning its content. Two kinds of
message are deleted at expiry instead of routed, as gc deletes them: a
member’s copy of a list post, whose envelope sender is the list’s bounce
processor, and a message whose content came out of, or failed to open from, a
ciphertext without integrity protection (telemetry decrypt-dropped). For
the second kind, whether the message was held at all can depend on the
padding of a ciphertext that its sender may have modified, so a report at the
end of the hold would answer the padding question.
The stage sends no notice of its own, to the sender or to the recipients.
The options are read from the base configuration, never from per-address settings: what a quarantine holds, and for how long, is the host’s decision.
A message that was released from a quarantine once and later reaches a quarantine stage again is held again. A sender of a quarantine request writes a fresh record, and the stage also starts a new hold for a record whose earlier hold ended.
Holds without MAX_HOLD are still bounded by pepsi-queue(1) gc,
which bounces a message held at a quarantine stage [pepsi-queue]
QUARANTINE_MAX_AGE_DAYS (default 14) days after its arrival, as it does for
every quarantine stage. A stage with MAX_HOLD ends its holds itself, and
gc leaves it alone. Mail that is held is plaintext at rest for as long as
it is held (a decrypt stage’s quarantine holds what it decrypted), which is
why some limit applies by default.
95.1.38.1.4. Configuration¶
Options live in the stage’s own [stage-<name>] section
(PROGRAM = pepsi-stage-quarantine); all are optional, but one of
RELEASE_STAGE and NEXT_STAGE must be set.
- RELEASE_STAGE = STAGE
Where a released message goes. Defaults to NEXT_STAGE. A message that ingress quarantined has skipped every stage before this one, so for that use it is normally
init. It must not be this stage itself.- MAX_HOLD = SPAN
How long a hold lasts at most, for example
14 days,2 weeksor36 h(a day counts as 24 hours; months and years are refused). Unset, a hold lasts until the message is released or deleted, within the limit of pepsi-queue(1)gc.- EXPIRE_STAGE = STAGE
Where a message goes when its hold reaches MAX_HOLD, for example a pepsi-stage-bounce(1) stage. Unset, an expired message is deleted (recorded in the opt-in mail log, like every deleted message). Refused without MAX_HOLD, since no hold could reach it, and refused when it is this stage itself.
The worker refuses to start (exit 78) when the section does not parse or a
stage that it names does not exist; pepsi-setup(1) validate refuses
the same. All options are documented in pepsi.conf(5).
95.1.38.1.5. State¶
Inputs: state.quarantine.reason and state.quarantine.by, if the
party that sent the message here wrote them; state.dsn and
state.crypto.in at expiry.
Outputs: the state.quarantine record, an object whose keys are
append-only across releases:
reason(string, optional)Why the message is held, as the party that sent it here put it (a milter’s
SMFIR_QUARANTINEtext).by(string, optional)Who sent it here:
milter:<MILTER_NAME>for a milter,stage:<name>for another stage.since(string, RFC 3339)When this stage began to hold the message.
until(string, RFC 3339)When the hold ends on its own, with MAX_HOLD.
released_at(string, RFC 3339)When the message was released.
expired(true)The hold reached
until.
The layout is described in pepsi.state(7).
Transitions:
first arrival, or a record whose earlier hold ended →
pausedat this stage,timeoutNULLor the end of MAX_HOLD;claimed again while held, before
until→ RELEASE_STAGE,pending;claimed at or after
until→ EXPIRE_STAGE,pending, or deleted.
95.1.38.1.6. Commands¶
- worker
Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.
95.1.38.1.7. Global Options¶
- -c FILE, –config FILE
Read the configuration from FILE instead of searching the default locations.
- -L LOGLEVEL, –log LOGLEVEL
Set the logging verbosity (default
[pepsi] LOG, elseinfo).- -v, –verbose
Show log messages from all sources.
- -h, –help; -V, –version
Print a usage summary / the version and exit.
95.1.38.1.8. Exit Status¶
The outcome of each message is reported to pepsi-dispatch(1) on the worker’s status line, not as the exit status.
- 0
The worker ran until its standard input was closed.
- 1
A fatal error occurred (unreadable configuration, the database could not be opened, or standard input/output failed). The reason is written to the log.
- 78
The stage’s section does not parse, or a stage that it names does not exist: the worker refuses to start, and pepsi-dispatch(1) holds the stage’s messages until the configuration is fixed.
95.1.38.1.9. Examples¶
A quarantine for a milter’s verdicts, released into the rest of the pipeline:
[stage-quarantine]
PROGRAM = pepsi-stage-quarantine
RELEASE_STAGE = init
[stage-spamfilter]
PROGRAM = pepsi-stage-milter
SOCKET = unix:/run/rspamd/milter.sock
ALLOW_ACTIONS = addhdrs chghdrs chgbody quarantine
QUARANTINE_STAGE = quarantine
NEXT_STAGE = deliver
A quarantine that ends a hold after two weeks with a DSN to the sender:
[stage-quarantine]
PROGRAM = pepsi-stage-quarantine
RELEASE_STAGE = init
MAX_HOLD = 2 weeks
EXPIRE_STAGE = bounce
List what is held, then release one message:
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine list
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine release TOKEN
95.1.38.1.10. See Also¶
pepsi-queue(1), pepsi-stage-milter(1), pepsi-stage-decrypt(1), pepsi-ingress(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)
95.1.38.1.11. Bugs¶
Report bugs to the Pepsi issue tracker.