panda-rpki-oss/docs/command-line-reference.md

# Command-line reference

This reference covers v0.1.0. `panda-rpki --help` displays version and usage;
there is no separate `--version` option.

## Syntax

```text
panda-rpki validate --tal FILE --ta FILE --out DIRECTORY [OPTIONS]
panda-rpki daemon --state-root DIRECTORY [DAEMON OPTIONS] -- [VALIDATION OPTIONS]
```

Use `--name value`, not `--name=value`. Only help has a short alias (`-h`).
Values are case-sensitive; options cannot repeat unless listed as repeatable.
Paths are relative to the process working directory. No configuration-file
option is provided. No arguments or a help request exits successfully.

## Inputs and outputs

| Option | Default / requirement | Repeatable | Meaning |
| --- | --- | --- | --- |
| `--tal <file>` | Required | Yes | Local TAL file. |
| `--ta <file>` | Required | Yes | Matching DER trust-anchor certificate. |
| `--tal-id <id>` | TAL filename stem | Yes | Anchor identifier; if supplied, provide one for every TAL. |
| `--ta-constraints <tal-id>=<file>` | Adjacent `.constraints` if present | Yes | Override constraints for a known TAL ID; each ID may occur once. |
| `--out <directory>` | Required | No | Output directory, created if absent. Existing output files may be overwritten. |
| `--ccr-out <file>` | Disabled | No | CCR DER path, relative to the working directory, not `--out`. |

TAL and TA lists are paired by occurrence order and must have equal lengths.
Use distinct TAL IDs. For `input/anchor.tal`, automatic discovery checks
`input/anchor.constraints`. If absent with no explicit path, no additional
constraints are loaded for that anchor.

## State and network

| Option | Default | Meaning |
| --- | --- | --- |
| `--rrdp-state-dir <directory>` | `<out>/.state` | Dedicated persistent root; database is stored in `repository-db/`. |
| `--rrdp-sync-mode <auto\|snapshot\|delta>` | `auto` | Starting state requirements described below. |
| `--http-timeout-secs <n>` | `300` | HTTP timeout seconds; nonnegative with runtime minimum 1. Connection, retry and large-object transport policies also apply. Not a whole-run deadline. |
| `--http-root-cert <pem>` | None | Repeatable extra HTTPS roots; system roots and hostname verification remain enabled. |
| `--max-ca-depth <n>` | `64` | Nonnegative CA traversal depth limit. |

| Mode | Starting state | Behavior |
| --- | --- | --- |
| `auto` | Empty or populated database | Select snapshot, delta or noop per repository. |
| `snapshot` | Missing or empty database | Start fresh; reject a populated database. |
| `delta` | Existing populated database | Resume state, allowing protocol snapshot fallback and new-repository snapshots. |

Unrecognized state layouts and unsupported database schemas are rejected.
Use a new dedicated directory for an incompatible format. State includes
repository objects, RRDP sessions and manifest anti-rollback metadata. Do not
share a writable database between processes. Changing `--out` changes default
state location unless `--rrdp-state-dir` is explicit.

RRDP references and redirects enforce HTTPS and same-origin rules. Extra
trust roots do not relax origin checks. No separate rsync timeout is exposed.

## Workers and queues

| Option | Default | Meaning |
| --- | ---: | --- |
| `--parallel-max-repo-sync-workers-global <n>` | 8 | Global repository transport workers. |
| `--parallel-phase2-object-workers <n>` | 8 | Object workers, independent of transport. |
| `--parallel-phase2-worker-queue-capacity <n>` | 256 | Object-worker queue capacity. |
| `--parallel-repo-worker-queue-capacity <n>` | 256 | Pending repository results; effective limit is `max(n, 1024)`. |

All values must be positive. Budgets are shared across TALs. Higher concurrency
can increase memory consumption and does not guarantee proportional speedup.

## Logging

| Option | Default | Values |
| --- | --- | --- |
| `--log-level <level>` | `info` | `off`, `error`, `warn`, `info`, `debug`, `trace` |
| `--log-format <format>` | `text` | `text`, `json` |

Precedence: explicit option, then `PANDA_RPKI_LOG_LEVEL` or
`PANDA_RPKI_LOG_FORMAT`, then default. Each level includes more severe messages.
`off` suppresses logs but does not change exit codes. JSON logs contain
`timestamp`, `level`, `event`, and `fields`, one object per line. Logs use stderr;
help uses stdout; validation results are written to files.

Other `PANDA_RPKI_*` variables in [Compose](docker.md) are template substitutions,
not configuration variables read directly by the binary.

## Daemon

Daemon runs in the foreground, launching this executable's `validate` command
in a separate process per cycle. Pass validator options after `--`, without
the word `validate`. The controller owns `--out`, `--ccr-out`,
`--rrdp-state-dir` and `--rrdp-sync-mode`; do not pass them after `--`.

| Option | Default | Meaning |
| --- | --- | --- |
| `--state-root <directory>` | Required | Dedicated root for state, lifecycle metadata and run outputs. |
| `--interval-secs <n>` | 60 | Wait after run recording and retention; zero starts the next run immediately. |
| `--max-runs <n>` | Unlimited | Positive attempt count for this invocation, including failed attempts. |
| `--retain-runs <n>` | 10 | Positive number of completed run directories retained, including recorded failures. Older completed directories are deleted. |
| `--run-timeout-secs <n>` | 0 | Whole-run deadline; zero disables. Sends SIGTERM to the child group, then SIGKILL after two seconds if needed. |
| `--shutdown-grace-secs <n>` | 30 | On SIGINT/SIGTERM, stop starting runs and wait at most n seconds before terminating the active process group. |

Options cannot repeat. Seconds are nonnegative. Empty state starts with
snapshot, successful continuation requests delta, and recovery after a failed
run with existing state requests auto. Actual operations can include noop and
snapshot fallback. Normal child failures/timeouts are recorded and retried;
corrupt lifecycle metadata or inability to record state stops the controller.

Restart continues numbering and reuses state. Retention leaves incomplete,
unrelated and symlink run directories untouched. It does not trim history JSONL.
Do not remove a live lock file. After SIGKILL, ensure the old validator child
has stopped before restarting. Stop the entire container for Docker deployments.

## Outputs and exit status

| File | Content |
| --- | --- |
| `summary.json` | TAL, worker, validation and actual RRDP operation counts. |
| `vrps.csv` | ROA payloads: `asn,prefix,max_length`. |
| `vaps.csv` | ASPA payloads. |
| `stage-timing.json`, `analysis/timing.json` | Timing and analysis counters. |
| `.vrps-source.csv` | Intermediate CSV used to produce `vrps.csv`. |
| Requested CCR path | Optional CCR DER; automatic per run in daemon mode. |

Daemon adds `daemon.lock`, `daemon-status.json`, `lifecycle.json`,
`run-summary.jsonl`, `state/repository-db/`, and `runs/run_000001/` etc.
Each run includes validator outputs, `run-meta.json`, `run-summary.json`,
`stdout.log`, `stderr.log` and optional `process-time.txt`. `/usr/bin/time`
provides user/system CPU and peak RSS when installed; Docker includes it.
Controller states: `starting`, `running`, `sleeping`, `exited`, `failed`.

Help and successful validation return 0; argument and propagated runtime
errors return 2. Completion can include rejected objects or recoverable
repository failures: inspect warnings and outputs too. Failed runs can leave
partial output; use a separate output directory per cycle.

A bounded daemon returns 2 if any attempt failed, otherwise 0. Stopping during
an interval exits normally. A forcibly terminated current run is recorded as
failed and causes exit 2.