136 lines
5.4 KiB
Markdown
136 lines
5.4 KiB
Markdown
# Command-line reference
|
|
|
|
For every field, default, constraint and complete example, see the [TOML configuration reference](configuration.md)。
|
|
|
|
Runtime settings come from one explicit TOML file; the binary does not read `PANDA_RPKI_LOG_*` overrides and
|
|
does not accept legacy validation flags.
|
|
|
|
## Commands
|
|
|
|
```text
|
|
panda-rpki --help
|
|
panda-rpki --version
|
|
panda-rpki -V
|
|
panda-rpki validate --help
|
|
panda-rpki daemon --help
|
|
panda-rpki validate --config FILE
|
|
panda-rpki validate --config FILE --check-config
|
|
panda-rpki validate --config FILE --print-config
|
|
panda-rpki daemon --config FILE
|
|
panda-rpki daemon --config FILE --check-config
|
|
panda-rpki daemon --config FILE --print-config
|
|
```
|
|
|
|
Only these long options are accepted: `--help`, `--version`, `--config`,
|
|
`--check-config` and `--print-config`. `-h` aliases help and `-V` aliases
|
|
version. `--config FILE` is required for a normal validate/daemon run and may
|
|
also be written as `--config=FILE`. Help does not read a config. Check and print
|
|
are mutually exclusive and do not run validation. Unknown, repeated or legacy
|
|
options—including a daemon `--` tail—return exit code 2.
|
|
|
|
## TOML schema
|
|
|
|
Every file contains `config-version = 1` and a matching `mode` value:
|
|
|
|
```toml
|
|
config-version = 1
|
|
mode = "validate"
|
|
out = "output"
|
|
rrdp-state-dir = "state"
|
|
rrdp-sync-mode = "auto"
|
|
ccr-out = "output/result.ccr"
|
|
publish-dir = "publish"
|
|
ta-refresh-policy = "allow-valid-cache"
|
|
require-complete = false
|
|
|
|
[[anchors]]
|
|
id = "ripe"
|
|
tal = "input/ripe.tal"
|
|
ta = "input/ripe.cer" # omit for automatic refresh from the TAL URI
|
|
constraints = "input/ripe.constraints"
|
|
```
|
|
|
|
All paths are relative to the TOML file, not the process working directory.
|
|
Absolute paths are accepted. `id` defaults to the TAL filename stem and must be
|
|
unique. `constraints` defaults to a same-stem `.constraints` file beside the
|
|
TAL. Automatic TA refresh supports HTTPS and rsync, validates the TAL binding,
|
|
signature and current validity, and stores a keyed cache at
|
|
`<rrdp-state-dir>.ta-cache/`. `allow-valid-cache` may use a still-valid cached
|
|
certificate when refresh fails and marks the run partial; `require-fresh` does
|
|
not fall back.
|
|
|
|
The remaining common keys and defaults are:
|
|
|
|
| Key | Default |
|
|
| --- | ---: |
|
|
| `max-ca-depth` | 64 |
|
|
| `http-timeout-secs` | 300 (0 is normalized to 1) |
|
|
| `http-root-cert` | `[]` |
|
|
| `parallel-max-repo-sync-workers-global` | 8 |
|
|
| `parallel-phase2-object-workers` | 8 |
|
|
| `parallel-phase2-worker-queue-capacity` | 256 |
|
|
| `parallel-repo-worker-queue-capacity` | 256 (effective minimum 1024) |
|
|
| `log-level` | `info` |
|
|
| `log-format` | `text` |
|
|
| `log-progress-interval-secs` | 10 |
|
|
| `run-timeout-secs` | 0 (disabled) |
|
|
| `require-complete` | `false` |
|
|
|
|
Validate-only keys are `out` (required), `rrdp-state-dir`, `rrdp-sync-mode`,
|
|
`ccr-out` and optional `publish-dir`. Daemon-only keys are `state-root`
|
|
(required), `interval-secs` (60), `max-runs` (unlimited), `retain-runs` (10)
|
|
and `shutdown-grace-secs` (30). Daemon does not accept validate-only keys; it
|
|
creates a per-run validate TOML internally.
|
|
|
|
## Inspection and outcomes
|
|
|
|
`--check-config` validates syntax, fields, local TAL/TA/constraints and existing
|
|
path types without network access, directory creation, state writes or locks.
|
|
`--print-config` emits `configVersion`, `mode`, `effective`, `sources` and
|
|
`normalizations` as JSON; defaults are filled and paths are absolute.
|
|
|
|
Strict validation, resource validation mode, validation time, RRDP/rsync
|
|
preference and all rsync tuning are TOML settings, not business CLI options.
|
|
Use `[strict]` plus the top-level `resource-validation-mode`,
|
|
`validation-time`, `sync-preference`, `rsync-timeout-secs`, `rsync-command`,
|
|
`rsync-mirror-root` and `rsync-scope` keys. `--print-config` exposes their
|
|
effective values and sources; an omitted validation time is generated for the
|
|
inspection and recaptured when an actual run starts.
|
|
|
|
Validation writes `summary.json`, `vrps.csv`, `vaps.csv`, timing files and an
|
|
optional CCR. The final `result-complete.json` is written only after all required
|
|
artifacts are ready. `resultStatus` is `success`, `partial` or `failed`:
|
|
|
|
| Status | Default exit | `require-complete = true` |
|
|
| --- | ---: | ---: |
|
|
| success | 0 | 0 |
|
|
| partial | 0 | 3 |
|
|
| failed | 2 | 2 |
|
|
|
|
`summary.json` adds `trustAnchors`, `taFailedCount`,
|
|
`repositoryFailedCount`, `taCacheFallbackCount`, `resultStatus` and
|
|
`publicationStatus`. A cache fallback or a failed anchor makes an otherwise
|
|
complete artifact set partial; rejected objects alone do not.
|
|
|
|
With `publish-dir`, only a complete success is copied to an immutable run:
|
|
|
|
```text
|
|
publish/runs/<run-id>/{vrps.csv,vaps.csv,summary.json,stage-timing.json,
|
|
analysis/timing.json,result-complete.json[,result.ccr]}
|
|
publish/latest -> runs/<run-id>
|
|
publish/last-attempt.json
|
|
```
|
|
|
|
`latest` changes atomically and never moves for partial or failed attempts.
|
|
Daemon uses its existing `state-root/runs/run_000001/` layout and atomically
|
|
points `state-root/latest` at the newest successful run; it retains completed
|
|
runs according to `retain-runs` while preserving the latest pointer.
|
|
|
|
## Configuration lifecycle
|
|
|
|
TAL files are never auto-updated. Omitting an anchor's `ta` field refreshes its
|
|
TA certificate on each cycle; providing `ta` selects fixed mode. TOML is read
|
|
once at process start. Put `log-format = "text"` and `ta-refresh-policy` at the
|
|
top level, before any `[[anchors]]` tables. See [Docker reload steps](docker.md#graceful-stop-edit-and-reload)
|
|
and [complete container TOML examples](../docker/examples/README.md).
|