Skip to content

Drush commands

Every operation the admin UI offers has a command, and a few exist only here. Run drush <command> --help for the full option list; the options below are the ones that decide what a command does rather than how it reports.

Exit codes are uniform across every command here, including the audit_trail_tsa ones:

  • 0: the command did what it says it does.
  • 1: the audited state is bad. A chain verified broken, an archive or a timestamp failed its checks. The command worked; the data is the problem.
  • 2: the command could not run. A missing or unusable option, a chain or archive id that does not exist, a lock it could not take, an error it could not anticipate. Nothing was learned about the audited state.

That split is the whole point of wrapping the verifier in a cron job: a typo in the crontab has to be distinguishable from a chain that actually broke. Both are non-zero, so || mail fires either way, and the code tells you which one to go and look at.

Verification

audit_trail:verify

Verifies the integrity of one or all chains. Incremental by default: the walk starts from the last signed checkpoint, which on a large chain is the difference between minutes and hours.

  • --chain=ID restricts the run to one chain.
  • --full walks every chain from genesis, ignoring checkpoints. At the default strict depth its verdict is also stored for the status report, the same way cron's full walk is: it records a break it finds, clears one it no longer finds, and logs the change on the audit_trail channel.
  • --depth=strict|tolerant|none says how much signature verification the walk performs, defaulting to strict. It requires --full: the incremental walk reads a signed checkpoint and mints another, and both need the signing secret. An unknown value is refused rather than falling back to one.

--depth and --full answer different questions: --full says where the walk starts, --depth says how much of the signing it checks. strict requires every secret to resolve and reports one that does not as a finding. tolerant checks what the resolvable secrets allow and names the rest, which is the walk for a keyring known to be incomplete: a site mid-rotation whose retired key has already been removed. none reads no signature at all, which is exactly what a reader without the keys gets. See verification for what each one proves.

A walk that cannot read a segment's signatures may still cross the gap its purge left, on the segment spine. The anchors a bridge uses are covered by the spine, which takes no secret, so none and a tolerant walk on a host without the keys cross a purged range when two things hold: the chain's spine replays, and a surviving segment_archived or segment_compacted event still corroborates a head at or past that segment's height. The segment is then listed in the verdict's unauthenticated_attestations, because the spine covers what a segment IS and never the purge claim on top of it.

Where either condition fails the gap is still reported as a broken link and the run exits 1: on a chain whose lifecycle events have all aged out, nothing corroborates the replay; and a consolidated row left by compaction is never spine-covered, so a range folded into one needs its signatures.

What those depths establish is that the rows still present link end to end and none has been edited. On a chain whose retention has never deleted a row, that covers the whole chain; on one whose retention has, it covers what survives. Read the result that way before handing a copy to an auditor, rather than as a pass or fail on the chain.

Exits 1 when any chain reports a break, which is what makes it usable directly as a cron or CI check.

audit_trail:acknowledge-reset

Records an operator acknowledgment that a chain range is unverifiable, so a known break (a secret lost in an incident, a restore that rewrote rows) stops being reported as an open finding. The acknowledgment is itself a signed, chained record: it does not erase the break, it explains it. The audit_trail_acknowledgment table is an index of those chain records, and audit_trail:reindex-acknowledgments rebuilds it from them.

The range has to be rows the chain still has. An acknowledgment is anchored to the stored hashes at its bounds and has to end at or before the chain head, so rows lost from the end of a chain, by a restore from an older backup for example, cannot be acknowledged: the command answers that to_id exceeds the head. Restoring those rows from their archive segment is what clears that finding.

The acknowledgment also signs the time of the newest row in its range, as the rows stand when you acknowledge them. Retention dates the acknowledged rows by that time from then on, never by their own created: an acknowledged row is excused whatever is edited on it afterwards, its time included.

  • --chain, --from, --to bound the range.
  • --reason is required, and is surfaced verbatim in the verifier output.

audit_trail:reindex-acknowledgments

Rebuilds the audit_trail_acknowledgment table from the chain events that record each acknowledgment.

The table is an index, not the record. Every acknowledgment is an acknowledgment_recorded chain event, and every change to one is an acknowledgment_updated or acknowledgment_deleted event, all signed and linked like any other chain row. Replaying them in id order reproduces the table, ids included.

Reach for it when the index and the chain have come apart: a restore from a partial backup, a DELETE against the table, a hand-edited range. The status report says when that has happened. Running it when nothing is wrong changes nothing, because the rebuild is what the chain already says.

  • --chain limits it to one chain. Omit it to cover every chain that has rows.
  • --dry-run reports what disagrees and changes nothing. It exits 1 when anything disagrees, so a monitoring script can watch for a damaged index.

An acknowledgment whose own chain events have been archived and live-purged cannot be rebuilt, and does not need to be: by then the rows it covered are gone as well, and the verifier bridges that range by the archive's signed anchors without asking about acknowledgments at all.

audit_trail:reindex-segments

Rebuilds the audit_trail_segment table from the chain events that record each segment.

The same story as the acknowledgment index above, on the table that carries the retention lifecycle. A segment is recorded before it exists: its segment_created event carries the whole identity envelope, and the audit_trail.id that event lands on becomes the segment's id. So the chain is the record and the table is a reading of it, and replaying the events reproduces the table, ids included.

Two entries on /admin/reports/status send you here, both at error severity. Audit trail segment index says the index and the chain disagree. Audit trail segment anchors says two neighboring segments no longer meet over rows that are gone, which is what a segment removed from between them looks like long after its own events aged out, or that the rows before the first segment are gone, which is what a removed first segment looks like.

  • --chain limits it to one chain. Omit it to cover every chain that has rows.
  • --dry-run reports what disagrees and changes nothing. It exits 1 when anything disagrees, so a monitoring script can watch for a damaged index. Run it first: it names what is missing from the index, what is in the index but not on the chain, and what differs.

Two segments that claim the same rows, or rows gone from between two segments or before the first one, exit 1 whether or not it is a dry run. That holds when the index agrees with the chain too, as it does once the events that recorded a removed segment have aged out. Rebuilding the index repairs neither, and what explains such a range is an acknowledgment.

Unlike an acknowledgment, a segment carries signatures, so a rebuild has to reseal them, under the secrets the chain names rather than the active one. A segment whose secret will not resolve here is left exactly as it is and reported as unsealable, because writing it with a signature nobody can verify would turn a recoverable gap into a permanent forgery finding.

For the same reason, a rebuild replays only events whose own signature holds: whatever it replays, it signs. An event written or edited without the secret is left out and named in a warning. The chain walk reports that row as broken as well, so run drush audit_trail:verify --full next.

Nothing is deleted. Only what the chain describes is rewritten. A row the replay cannot produce is not a row the chain denies: its events may have aged out, or come back from a backup older than the segment table beside them. --dry-run reports such a row as being in the index but not on the chain, and removing it stays a deliberate act.

Secrets

audit_trail:secret-fingerprints

Prints the settings.php lines that trust every configured secret whose Key can be read:

$settings['audit_trail_trusted_secrets'] = [
  '4da5b88e' => '4da5b88e6c0f…',
];

Paste them into settings.php so that a secret added through the database verifies and signs nothing. See Pinning what the module trusts. Exits 2 when no secret can be read.

Once pinned, it prints only the secrets already trusted. --add=<id>[,<id>] adds the ones you created, named by the ID the secrets page shows.

audit_trail:set-signing-secret

--key is required, and names the drupal/key Key entity whose bytes the signing secret uses.

Makes the secret backed by that Key the one that signs new rows. It does not create key material: provision the Key in whatever provider your policy requires, and this points a secret at it, creating the audit_trail_secret record if there is not one already. The new secret is activated first and the outgoing one retired right after, so a crash part-way leaves two active secrets (harmless, and the status report says so) rather than none, which would halt writes.

A Key that already backs the signing secret is refused: pointing at the same bytes again would read as a rotation in the trail while nothing about the signing changed. So is a Key holding the same bytes as any other secret, under whatever Key entity: the secret id is computed from the bytes, so the two would carry the same id.

audit_trail:retire-secret

Retires a secret without activating a replacement. When the retired secret was the only active one, chains stop accepting writes until another is activated, which is the point: it is the command for taking a compromised key out of service. Retiring a pending candidate, or one of the two actives a crashed rotation leaves behind, keeps writes running under the survivor, and the command reports which secret that is.

  • --id=MACHINE_NAME retires a specific secret, named by its machine name, instead of the active one. A name no secret has stops the command and retires nothing.

Retention lifecycle

The six stages run from cron. These commands drive the same machinery by hand, for a one-off range or for an operator who wants to watch a stage before enabling it.

audit_trail:apply-retention

Runs the retention lifecycle on demand, applying whatever the configured thresholds say is due right now.

  • --chain=ID restricts the run to one chain.

The admin pages run the same thing: Apply retention to all chains at the top of the chains page, Apply retention now on the settings page, and the Apply retention operation of one chain.

audit_trail:archive

Exports a chain segment to NDJSON and records the archive row, with the file's SHA-256 captured in the same row so later tampering with the file surfaces at verify time.

  • --chain, --from, --to bound the range.
  • --directory overrides the configured archive directory.

audit_trail:purge

Drops a previously-archived range from the live audit_trail table. The segment row stays as the verifier's bridge across the gap.

  • --id=N names the segment.
  • --dry-run reports what would go without touching anything.

audit_trail:compact

Compacts contiguous file-purged segments into a single bridging row. Hygiene only: it closes the open-ended tail the lifecycle otherwise leaves behind, and it changes nothing a verifier can observe.

  • --chain names the chain. --before='ISO date' is required and bounds what is eligible: only file-purged segments covering rows created strictly before it. There is no implicit cutoff, because a default of now would have made the shortest invocation the widest one.
  • --dry-run prints which segments would be folded and touches nothing.
  • A segment carrying verification_failed_at_purge is never folded, and splits any run it sits inside. Its range is what an acknowledgment has to cover to explain it, so widening the range would stop an explanation already recorded from covering the segment.
  • Every segment's identity and lifecycle signatures are checked before folding, and one that does not hold, or that names a secret id no secret has, refuses the whole run: the fold would sign whatever that row says. Such a segment was changed without the signing secret, so run drush audit_trail:verify --full.

audit_trail:rewrite-archive

Rebuilds an archived segment's NDJSON from its still-live rows, for the case where the file has gone missing from the archive directory.

live-purge refuses such a segment, because it is about to delete the last live copy of the range and the copy meant to replace it is not there. Left alone that stalls indefinitely, which is its own problem: rows sit past the retention window they were given. The rows are untouched though, which is exactly why the refusal happened, so the file can be written again from them.

  • --id names the segment.
  • Refused unless the rebuilt bytes match the SHA-256 recorded when the segment was archived, so it restores what was attested or nothing at all. The archive is deterministic and an archived segment's rows are frozen, so a mismatch means the rows no longer agree with what was signed: verify the chain rather than rebuilding over it.
  • Also refused if the file is still there, if the segment was never archived, or if its rows have already been live-purged.
  • Those refusals do not all mean the same thing, and the exit code says which. Rows that no longer produce the digest they were signed with exit 1: the trail is the problem, and the message says to verify the chain. Every other refusal exits 2, a file still on disk and an id that does not exist included, because nothing was learned about the trail. A || mail wrapper should page on the first and not on the second.
  • Once it succeeds, live-purge proceeds on its normal schedule. Nothing is re-signed and no lifecycle stamp moves.

Archives

audit_trail:archive-verify

Verifies an archive record against its on-disk NDJSON file, recomputing the SHA-256 and the lifecycle HMAC.

  • --id=N names the segment, --path points at a file that has been moved since it was written.
  • --path alone checks a file with no segment: the archive of a chain that has started again since, which an import refuses. It checks the footer's signature, that the rows link from its first anchor to its last, and each row's hash and signature. A row whose secret this site does not hold is counted, not checked.
drush audit_trail:archive-verify --path=/mnt/worm/webdav-12.ndjson

audit_trail:archive-open

Opens archive files to read and search their rows on the Archived entries tab of the report: any archive, of any chain, several at once. Nothing is checked or restored. See Reading archives.

drush audit_trail:archive-open /mnt/worm/webdav/2025-*.ndjson

audit_trail:archive-close

Drops the rows opened from archive files; --source closes one archive only. The archive files and the audit trail are not touched.

audit_trail:archive-import

Imports an NDJSON archive file as a fresh audit_trail_segment row. This is the disaster-recovery entry point: it is how an archive pulled back from WORM storage becomes known to a site whose database no longer has the segment.

  • --path is the file.
  • --restore also brings the rows back in the same run.
  • --allow-missing-secret accepts a file signed under a secret this site registers but whose Key it cannot read. It is logged as a critical event, because it accepts content the site cannot cryptographically attribute. It does not accept a secret settings.php refuses, nor one this site does not have at all: such a file is read with audit_trail:archive-open. Restored rows keep the signatures they were archived with; the verifier reports the ones it cannot check.

An import is there to read an archive's rows again for a while: --restore puts them back where they were, and the live-purge stage takes them out again on its next eligible run. So the archive has to be of the chain as it is: the chain goes on from where the archive ends, and any row of its range still in the database is the archive's own. A chain cleared since, or a database rebuilt, has started again, and its ids with it, so the archive's would name rows of the new chain. The import is refused: audit_trail:archive-open reads it, and audit_trail:archive-verify --path checks it. An archive whose rows are gone is recorded as live-purged; one whose rows are still there, its segment row lost, is recorded as archived, and retention purges it as usual.

A segment row lost from the database is still named by the chain's own segment events, and audit_trail:reindex-segments rebuilds it from them. An import over its rows would leave two segments over the same rows once that rebuild runs, so it is refused while any segment event on the chain names a segment over a row of the archive's range:

drush audit_trail:reindex-segments --chain=webdav
drush audit_trail:archive-restore --id=<the segment the refusal names>

The import is for the archive of a segment whose events are gone too, archived and live-purged by a later segment.

Rows whose transient context was purged before their archive come back without it. The import records that transient-purge on the chain, since the one that emptied them is no longer there, and the verifier accepts an emptied column only on a segment's transient-purge.

A file whose footer names a chain id that is not a machine name is refused either way, before anything is written: the id names the directory the archive is copied into. So is a footer whose range does not start at row 1 or later and end at or after its start, because the range is what the segment records.

The rows have to link from the footer's first anchor to its last one, each hashed from what the file holds, or the file is refused. Nothing else in the file is signed, so that is what proves no row was dropped or rewritten. A row edited in the database before it was archived does not hash to what the next row links to, so an archive holding one is refused here, acknowledged or not. While the site still has its segment, audit_trail:archive-restore brings those rows back, as they were stored.

audit_trail:archive-restore

Restores a previously-purged archive back into the live table.

  • --id=N names the segment, --path overrides the recorded file location, --allow-missing-secret behaves as above. It waives a lifecycle signature only when the secret is one this site knows whose Key cannot be read.

Each row comes back with the signature it was archived with, never one signed at restore: a row rewritten before it was archived stays reported as broken.

An acknowledgment is honored while the chain row recording it is live. Once that row has been purged in its turn, restoring a segment the acknowledgment explained and purging it again marks the segment as purged unexplained: acknowledge its range again before the purge, or after it, and the verdict names that reason. A row whose transient context does not match its signed hash comes back as archived, is named in the output, and is reported by the walk.

A segment whose file retention has deleted is not restored: its range is at the end of its lifecycle. A copy of its archive is read in the archived entries, with audit_trail:archive-open.

The next retention run re-purges restored rows, on cron or on demand, since restoring clears the segment's live-purge stamp and the retention ceiling applies again. Turn off retention on cron and start no other retention run, or lift live_purge_after, if the restore is for an inspection window. The command says so on success too, so this is not something an operator has to have read first.

A restore that used --path records that path in the segment_restored chain event's permanent bucket. The derived location is always reconstructed from the directory setting, the chain and the segment id; an override is not, so without recording it a restore from a WORM copy left no account of where the rows came back from. It is in the permanent bucket rather than the transient one, so retention cannot remove the provenance later.

Outbox

audit_trail:retry-abandoned

Offers again every outbox entry the flush gave up on. An entry written inside a transaction waits in the outbox until it is chained, and one that still fails after three flushes, for example because no secret was active, is abandoned: kept, counted as an error on the status report, and never offered again by itself. Once the cause is fixed, this resets their attempts, and the next cron run records them; follow it with drush cron to record them now. An entry that fails again is abandoned again; the PHP error log, not the site log, has one audit_trail line per failed attempt, saying why.

An entry written at or before the end of the history retention has already purged from its chain is refused rather than recorded: by then it cannot be told from a copy of a row chained long ago. Retry abandoned entries well inside the chain's live-purge window.

Timestamping

Both commands come from the audit_trail_tsa submodule.

audit_trail:timestamp

Anchors a chain head to the configured RFC-3161 TSA. One round trip per chain; the response lands as a chained tsa_timestamp row, so the timestamp is itself covered by the chain's HMAC.

  • --chain=ID for one chain, --all for every chain that still accepts writes.

--all is a sweep and skips an inactive chain on the chains list, the way the cron tick does: a timestamp is a row on the chain, and an inactive chain takes no new rows. --chain=ID stamps one regardless, so the final state of a chain just made inactive can still be anchored: that is an operator asking for one timestamp rather than a timer adding one every interval.

The Timestamp all chains button, at the top of the chains page and on the TSA settings page, runs the cron pass at once. Like cron, it skips a chain that opted out of TSA and a chain whose head is already a timestamp. Unlike cron, it does not wait for the interval, and it runs with cron timestamping off. With TSA timestamping itself switched off, it stamps nothing and says so.

audit_trail:verify-timestamp

Verifies a stored TSR via openssl ts -verify, against the operator-supplied CA chain configured on the provider. This is the offline check: the TSR is already HMAC-bound by being a chain row, and this adds the authority's own signature on top, that the timestamp covers the anchor the row claims, and that the anchor is the chain's own hash at the row it says it anchored. One openssl call establishes the first two; a second runs only to explain a row that failed them.

  • --row-id=N for one row, --chain=ID for every timestamp on a chain. The chain form exits non-zero if any of them fails.

The openssl command-line tool has to be installed on the host running the command. Its absence is flagged on the status report whenever timestamping is enabled.

The last of those checks is a database read, so it runs for a provider with no CA chain pinned too. Such a row exits 2, nothing having been learned about the authority's signature, unless the anchor is not the chain's own hash: that is a finding the command can make without a CA, and it exits 1.