rsyslog-segqueue¶

rsyslog-segqueue is an offline maintenance utility for version 2 segmentedDisk stores. It provides fast status, complete integrity checks, lossless JSONL export, conservative state reconstruction, and salvage repair.

Use this tool on the dedicated <workDirectory>/<queue.filename>.segq/ directory. It does not support classic .qi queues or the rejected experimental version 1 format.

Safety model¶

Status, check, and export are read-only. Stop rsyslog before applying any repair: the utility can detect files that change during preparation, but the daemon and utility do not share a lock protocol.

Repair runs in plan-only mode unless both --apply and --offline are present. A state-slot repair retains a timestamped copy of the old state file. Rebuild and salvage create and validate a sibling store, rename the original to a timestamped backup, and atomically install the replacement. No backup is removed automatically.

When state cannot prove which records were committed, rebuild and salvage make every recovered record pending. This can produce duplicates, but avoids silently discarding recoverable log records.

Commands¶

status QUEUE-DIR [--json]: Read state slots and segment metadata without scanning record payloads.
check QUEUE-DIR [--json]: Validate the state file, topology, segment headers and footers, record framing and checksums, and every persisted TLV message.
export QUEUE-DIR [--output FILE|-] [--scope live|all] [--salvage]: Write one JSON object per record. live is the default scope and begins at the durable commit frontier. all includes already committed physical data. Corruption is fatal unless --salvage is selected.
repair QUEUE-DIR --mode state-slot|rebuild|salvage: Produce a no-write plan. Add --apply --offline to apply it. state-slot restores redundant state, rebuild requires clean segment data, and salvage copies every independently verified record into a normalized store.
tui [QUEUE-DIR]: Open a guided, dependency-free terminal menu over the same operations.

JSONL schema¶

Each line contains a queue object with the source segment, byte offsets, and local record sequence, plus a message object containing every persisted message property. msg and rawmsg_after_pri are derived from the stored offsets. Embedded message JSON and local variables remain nested JSON values. An unparsed message may carry rsyslog’s unsigned 0xffffffff offset sentinel; in that case msg contains the complete raw message and msg_offset_unset is true.

Text fields are JSON strings when they contain valid UTF-8. Otherwise the field is an object such as {"encoding":"base64","data":"..."}, preserving the original bytes without replacement characters.

Exit codes¶

0: Success with no integrity errors.
1: Invalid invocation, filesystem failure, or internal processing error.
2: Integrity errors were found, or salvage export completed with omissions.

Examples¶

rsyslog-segqueue status /var/spool/rsyslog/mainq.segq
rsyslog-segqueue check --json /var/spool/rsyslog/mainq.segq
rsyslog-segqueue export /var/spool/rsyslog/mainq.segq --output backlog.jsonl
rsyslog-segqueue repair /var/spool/rsyslog/mainq.segq --mode salvage
rsyslog-segqueue repair /var/spool/rsyslog/mainq.segq \
  --mode salvage --apply --offline