70.1.31. pepsi-queue

inspect and repair the pepsi-ingress message queue

Manual section:

1

70.1.31.1.1. Name

pepsi-queue - list, delete, re-stage and unstick messages in the ingress queue.

70.1.31.1.2. Synopsis

pepsi-queue [GLOBAL-OPTIONS] [list] [–json] [–state-only] [–limit N] [–stage STAGE] [–status STATUS] [INGRESS-ID]

pepsi-queue [GLOBAL-OPTIONS] delete INGRESS-ID

pepsi-queue [GLOBAL-OPTIONS] set-stage INGRESS-ID STAGE

pepsi-queue [GLOBAL-OPTIONS] clear-all

pepsi-queue [GLOBAL-OPTIONS] gc

70.1.31.1.3. Description

pepsi-queue is a diagnostic and repair tool for the pepsi.ingress table shared by the Pepsi pipeline. Every accepted message advances through a filter pipeline tracked by three columns on each row: a stage (the configuration section of the program currently responsible for the message; init for a freshly accepted message), a status (pending, running, paused, failed or timeout), and an optional JSON state (per-stage scratch data). See pepsi.conf(5) for the stored-data layout.

The tool connects to the same database as the other components, through the shared [pepsi-postgres] section; it introduces no configuration of its own. When started as root it continues as the pepsi service account, which owns the queue; see Running as root.

Note

The mutating subcommands act immediately and are not reversible. In particular delete removes a message permanently, and set-stage / clear-all change processing state in place. They do not emit a database notification, so they are safe to run while the pipeline is idle.

70.1.31.1.4. Commands

list [–json] [–state-only] [–limit N] [–stage STAGE] [–status STATUS] [INGRESS-ID]

List queued messages, ordered by ingress_id. This is also the default action when no subcommand is given, so the list keyword may be omitted: pepsi-queue lists everything and pepsi-queue 5 shows only the message with ingress_id 5.

INGRESS-ID

An optional trailing message id. When given, only that one message is shown (the other filters and --limit are then moot). pepsi-queue 5 and pepsi-queue list 5 are equivalent.

–json

Emit a JSON array of objects (ingress_id, stage, status, mail_from, subject, received_at, state) instead of the human-readable table.

–state-only

Print each matching message’s full, un-truncated JSON state (the table view abbreviates it), one pretty-printed block per message. With an explicit INGRESS-ID the output is just that message’s state, so pepsi-queue --state-only 5 prints the complete state of message 5 — convenient to pipe into a JSON tool.

–limit N

Show at most N messages. Defaults to 100. Ignored when an INGRESS-ID is given.

–stage STAGE

Only show messages whose stage equals STAGE.

–status STATUS

Only show messages with the given status.

delete INGRESS-ID

Permanently delete the message with the given ingress_id.

set-stage INGRESS-ID STAGE

Re-assign the message to STAGE and implicitly reset its status to pending so the new stage picks it up. The message’s state is left unchanged.

clear-all

Reset every message whose status is running or paused back to pending — the bulk “unstick” used after a crash or a stalled stage. Messages in failed or timeout are left untouched.

gc

Garbage-collect the proof-of-origin nonce table (pepsi.origin_nonce), deleting every entry whose two-week expiration has passed. An expired nonce can no longer authenticate a returning bounce, so dropping it is safe. Intended to run periodically; the Debian package ships a pepsi-origin-gc.timer that invokes it hourly. See pepsi-stage-relay-to-internet(1) (which records the nonces) and pepsi-stage-anti-spam(1) (which verifies them).

70.1.31.1.5. Running as root

Pepsi gives every component its own PostgreSQL role, authenticated over the local socket by the operating-system account it runs as, and root is deliberately not one of them. Rather than fail to connect and oblige you to remember sudo -u pepsi pepsi-queue …, the tool detects that it was started as root and becomes the unprivileged pepsi service account — the account the dispatcher runs as, which owns pepsi.ingress — before it connects. The change is permanent for the life of the process; the tool needs no privilege of its own.

The configuration file (and any @inline-secret@ fragment it references) is read before the switch, so a root-only configuration is still loaded normally.

If the pepsi account does not exist — an uninstalled source tree, a test rig — the identity is left untouched, a warning is logged, and the connection is attempted as the invoking user, so a setup in which root can reach the database keeps working.

70.1.31.1.6. Global Options

These global options precede the subcommand (a trailing flag is rejected).

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity. LOGLEVEL is one of error, warn, info, debug or trace (default: info).

-v, –verbose

Show log messages from all sources, including third-party libraries.

-h, –help

Print a usage summary and exit.

-V, –version

Print the version and exit.

70.1.31.1.7. Exit Status

0

Successful completion.

1

An error occurred: a malformed configuration file or a failed database connection or query. The reason is written to the log.

70.1.31.1.8. Examples

List the first 20 queued messages as a table:

pepsi-queue -c /etc/pepsi/pepsi.conf list --limit 20

Show, as JSON, every message currently held by the spamfilter stage:

pepsi-queue -c /etc/pepsi/pepsi.conf list --json --stage spamfilter

Inspect just message 5, then dump its complete state JSON:

pepsi-queue -c /etc/pepsi/pepsi.conf 5
pepsi-queue -c /etc/pepsi/pepsi.conf --state-only 5

Hand message 42 to the spamfilter stage again:

pepsi-queue -c /etc/pepsi/pepsi.conf set-stage 42 spamfilter

Recover after a crash by re-queuing everything that was in flight:

pepsi-queue -c /etc/pepsi/pepsi.conf clear-all

70.1.31.1.9. See Also

pepsi-status(1), pepsi-config(1), pepsi-ingress(1), pepsi.conf(5), pepsi-setup(1)

70.1.31.1.10. Bugs

Report bugs to the Pepsi issue tracker.