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.since and leaves the row paused. Without MAX_HOLD the row has no timeout, so pepsi-dispatch(1) never wakes it on its own; the message waits until someone acts. With MAX_HOLD the timeout is the end of the hold, and state.quarantine.until records it.

  • On release (pepsi-queue quarantine release, or an operator’s pepsi-queue set-stage or administrative requeue to this stage) the row comes back to this stage as pending. The stage records released_at and sends the message on to RELEASE_STAGE. The POST /resume webhook 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 expired and 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 weeks or 36 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_QUARANTINE text).

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 → paused at this stage, timeout NULL or 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, else info).

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