157 lines
5.5 KiB
Markdown
157 lines
5.5 KiB
Markdown
# Usage
|
|
|
|
For every field, default, constraint and complete example, see the [TOML configuration reference](configuration.md)。
|
|
|
|
Panda RPKI reads one TOML file at process start. Copy the file to create a
|
|
different profile; there is no command-line business-option or environment
|
|
override.
|
|
|
|
## Snapshot, delta and automatic refresh
|
|
|
|
```toml
|
|
config-version = 1
|
|
mode = "validate"
|
|
out = "output/ripe"
|
|
rrdp-state-dir = "state/ripe"
|
|
rrdp-sync-mode = "auto"
|
|
ccr-out = "output/ripe/result.ccr"
|
|
publish-dir = "publish/ripe"
|
|
|
|
[[anchors]]
|
|
id = "ripe"
|
|
tal = "input/ripe.tal"
|
|
# ta = "input/ripe.cer" # leave out to refresh from the TAL URI
|
|
```
|
|
|
|
```bash
|
|
panda-rpki validate --config validate.toml --check-config
|
|
panda-rpki validate --config validate.toml
|
|
```
|
|
|
|
An empty state selects a snapshot. After a successful run, `auto` can use
|
|
delta updates; after an incomplete or failed run it recovers with `auto`.
|
|
Explicit `snapshot` requires an empty state and `delta` requires an existing
|
|
database. A valid downloaded TA is cached beside the state directory using the
|
|
TAL public-key hash. Refresh failures may use that cache under
|
|
`allow-valid-cache` and produce `partial`; use `require-fresh` to reject the
|
|
fallback.
|
|
|
|
Automatic TA refresh compares usable fetched and cached certificates using the
|
|
[TA tiebreaker rules](configuration.md#5-anchor-fields). A preferred cached
|
|
certificate after a successful fetch keeps the run successful. RRDP also checks
|
|
the previous notification's delta hashes (RFC 9697); a changed hash within the
|
|
same session emits `rrdp_session_desynchronized` and triggers a fresh snapshot,
|
|
including when the notification serial has not advanced. This check uses stored
|
|
hashes and does not fetch old deltas.
|
|
|
|
## Multiple anchors and constraints
|
|
|
|
Use one named `[[anchors]]` table per RIR. There is no positional TAL/TA pairing:
|
|
|
|
```toml
|
|
config-version = 1
|
|
mode = "validate"
|
|
out = "output/all5"
|
|
rrdp-state-dir = "state/all5"
|
|
ccr-out = "output/all5/result.ccr"
|
|
|
|
[[anchors]]
|
|
id = "afrinic"
|
|
tal = "input/afrinic.tal"
|
|
# ta = "input/afrinic.cer" # uncomment for fixed TA mode
|
|
|
|
[[anchors]]
|
|
id = "apnic"
|
|
tal = "input/apnic.tal"
|
|
# ta = "input/apnic.cer" # uncomment for fixed TA mode
|
|
|
|
[[anchors]]
|
|
id = "arin"
|
|
tal = "input/arin.tal"
|
|
# ta = "input/arin.cer" # uncomment for fixed TA mode
|
|
|
|
[[anchors]]
|
|
id = "lacnic"
|
|
tal = "input/lacnic.tal"
|
|
# ta = "input/lacnic.cer" # uncomment for fixed TA mode
|
|
|
|
[[anchors]]
|
|
id = "ripe"
|
|
tal = "input/ripe.tal"
|
|
# ta = "input/ripe.cer" # uncomment for fixed TA mode
|
|
constraints = "input/ripe.constraints"
|
|
```
|
|
|
|
An omitted `constraints` field discovers a same-stem file beside the TAL. An
|
|
explicit path must exist and parse. Constraint rules follow the profile in the
|
|
[standards matrix](conformance-matrix.md).
|
|
|
|
## Manifest history
|
|
|
|
The unreleased RFC 9981 implementation requires a fresh state directory. It
|
|
directly uses CA public-key history within the TAL public-key namespace; there
|
|
is no old-database migration or fallback. Reuse that new directory on subsequent
|
|
runs to retain replay protection across restarts and CA certificate reissuance.
|
|
|
|
A manifest filename change can restart the number sequence, but its thisUpdate
|
|
must still advance. Alternative CA SIA entries participate in the filename
|
|
comparison; changing only a directory does not reset the number. A rename is
|
|
reported to the operator, including when the candidate later fails validation.
|
|
The EE signedObject URI must exactly match the actual published rsync URI for
|
|
both RRDP and rsync. Failed manifests do not advance history or emit their
|
|
payloads; they make the CLI result partial and trigger exit code 3 when
|
|
`require-complete = true`.
|
|
|
|
## Continuous operation
|
|
|
|
Daemon configuration keeps the controller and validator settings together:
|
|
|
|
```toml
|
|
config-version = 1
|
|
mode = "daemon"
|
|
state-root = "data/all5-daemon"
|
|
interval-secs = 600
|
|
# max-runs = 3 # uncomment for a finite three-cycle run
|
|
retain-runs = 10
|
|
run-timeout-secs = 1800
|
|
shutdown-grace-secs = 30
|
|
require-complete = true
|
|
ta-refresh-policy = "allow-valid-cache"
|
|
log-format = "text"
|
|
log-level = "info"
|
|
|
|
[[anchors]]
|
|
id = "ripe"
|
|
tal = "input/ripe.tal"
|
|
# ta = "input/ripe.cer" # uncomment for fixed TA mode
|
|
```
|
|
|
|
```bash
|
|
panda-rpki daemon --config daemon.toml --check-config
|
|
panda-rpki daemon --config daemon.toml
|
|
```
|
|
|
|
Each cycle writes `data/all5-daemon/runs/run_000001/`, including the generated
|
|
`validator-config.toml`, CSV/CCR/summary/timing artifacts, process metrics and
|
|
logs. The daemon points `data/all5-daemon/latest` at the newest successful run;
|
|
partial and failed runs remain available for diagnosis. It chooses snapshot for
|
|
empty state, delta after success and auto after partial/failed recovery. A
|
|
finite daemon exits 2 if any run failed, 3 when only partial runs occurred and
|
|
`require-complete` is true, otherwise 0.
|
|
|
|
## Outputs and diagnostics
|
|
|
|
`summary.json` and `result-complete.json` describe the current attempt. Use the
|
|
immutable `publish/latest` (validate with `publish-dir`) or daemon `latest` when
|
|
consumers need a consistent group of files. `validator.log` contains structured
|
|
diagnostics on stderr; `--print-config` is configuration JSON and does not
|
|
contain validation payloads.
|
|
|
|
For path, state-layout, RRDP origin or permission errors, inspect the error
|
|
first and preserve the existing state directory. Do not share a writable state
|
|
directory between concurrent instances.
|
|
|
|
TAL files themselves are operator-maintained; automatic refresh changes only
|
|
TA certificates in the cache. See [stop/edit/reload](docker.md#graceful-stop-edit-and-reload)
|
|
for Docker shutdown semantics, text logging changes and switching anchor modes.
|