yuyr/panda-rpki-oss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

20260914 强制 TOML 配置并完善 TA 刷新与 daemon
Some checks failed
ci / rust (push) Has been cancelled
Details
ci / docker (push) Has been cancelled
Details
ci / audit (push) Has been cancelled
Details

Browse Source
This commit is contained in:
yuyr
2026-09-14 16:58:08 +08:00
parent 6383e2c12c
commit 4975128945
48 changed files with 2795 additions and 1459 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
docs/usage.md
View File

@@ -1,110 +1,132 @@
# Usage
Examples assume `panda-rpki` is on PATH; for a local build use
`target/release/panda-rpki`. Prepare TAL/TA files as described in
[Getting started](getting-started.md).
For every field, default, constraint and complete example, see the [TOML configuration reference](configuration.md)。
## Snapshot and delta
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.
Use a fresh state directory for an explicit snapshot:
## Snapshot, delta and automatic refresh
```bash
panda-rpki validate --tal input/anchor.tal --ta input/anchor.cer \
--rrdp-state-dir state/anchor --rrdp-sync-mode snapshot \
--out output/snapshot --ccr-out output/snapshot/result.ccr
panda-rpki validate --tal input/anchor.tal --ta input/anchor.cer \
--rrdp-state-dir state/anchor --rrdp-sync-mode delta \
--out output/delta-01 --ccr-out output/delta-01/result.ccr
```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
```
Subsequent runs reuse state and can use `auto`. Delta mode can include a
protocol-required snapshot or noop. Check actual operation counters in the
summary. Do not discard persistent state between scheduled runs.
```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.
## Multiple anchors and constraints
```bash
panda-rpki validate \
--tal input/arin.tal --ta input/arin.cer --tal-id arin \
--tal input/ripe.tal --ta input/ripe.cer --tal-id ripe \
--parallel-max-repo-sync-workers-global 8 \
--parallel-phase2-object-workers 8 \
--rrdp-state-dir state/multi --out output/multi \
--ccr-out output/multi/result.ccr
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"
```
Add further pairs in the same way. Optional resource constraints are read from
the TAL-adjacent `.constraints` file, or specified with
`--ta-constraints arin=input/arin.constraints`. Rules follow the WG profile
listed in the [standards matrix](conformance-matrix.md).
A constraint file contains `allow`/`deny` followed by an IPv4/IPv6 prefix,
address range, ASN or ASN range. Blank lines and `#` comments are allowed.
For a synthetic test anchor, an example is:
```text
# Example resources only: do not apply this policy to a production RIR.
allow 192.0.2.0/24
deny 192.0.2.128/25
allow 2001:db8::/32
allow 64496 - 64511
```
Deny overlap rejects an EE resource; otherwise the resource must be fully
covered by allow rules of its resource family. Unlisted resources are not
implicitly allowed. An empty constraint file therefore differs from having
no constraint file. Overlapping rules are normalized and may produce warnings.
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).
## Continuous operation
```bash
panda-rpki daemon --state-root data/daemon \
--interval-secs 600 --retain-runs 10 -- \
--tal input/anchor.tal --ta input/anchor.cer \
--log-level info --log-format json
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
```
The daemon runs in the foreground. It starts with snapshot for empty state and
requests delta after successful runs. The interval starts after each cycle
finishes. Add `--max-runs 3` before `--` for a finite run. SIGTERM requests a
graceful stop. Restart with the same root to continue numbering and state.
```bash
panda-rpki daemon --config daemon.toml --check-config
panda-rpki daemon --config daemon.toml
```
Each cycle writes to `data/daemon/runs/run_000001/`, then `run_000002/`, etc.
Retention deletes the oldest completed run directories beyond the configured
limit, including their artifacts. Copy anything you need to retain elsewhere.
The append-only summary history is not trimmed by retention.
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
`validator.log` is the per-run diagnostic log, not an error-only file.
`process-output.txt` captures ordinary child output and is normally empty.
Old runs keep their historical filenames; collectors support `stderr.log` as a fallback.
Every ten seconds, info logs report the current stage and available progress counters.
Use `--log-progress-interval-secs 0` to disable periodic events; stage events remain.
`statistics_age_ms` identifies stale statistics; `progress_stalled` means no observed
completion for thirty seconds, not a proven deadlock. Totals and percentages are not guessed.
Events include `run_id` and, under daemon, `run_seq`. Controller logs remain separate.
`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.
`vrps.csv` contains `asn,prefix,max_length`. CCR contains canonical state;
duplicate routing payloads can collapse into a single CCR entry. Count raw
rows and normalized unique payloads separately when comparing outputs.
ASPA canonicalization groups providers by customer ASN.
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.
Use `--log-level debug` for diagnosis, or `trace` for detailed object/worker
events. Logs are written to stderr and can be redirected independently from
outputs. In daemon mode, inspect per-run `validator.log` and the controller's
`daemon-status.json` and `run-summary.jsonl`.
| Symptom | Action |
| --- | --- |
| TAL/TA key mismatch or expired TA | Refresh the certificate from the TAL's official URI and check the selected pair. |
| State-layout/schema error | Preserve the directory and select a new dedicated root for a compatible run. |
| Snapshot refuses existing state | Use `auto`/`delta`, or choose a fresh directory for a new snapshot. |
| Delta refuses empty state | Establish state with `auto` or `snapshot`. |
| Permission denied in Docker | Pre-create writable host directories and use your UID/GID mapping. |
| RRDP origin rejection | Inspect the publisher's notification/references; extra TLS roots do not bypass origin policy. |
| Daemon root locked | Stop the other instance normally; do not delete its lock file. |
| Unexpected counts or partial output | Inspect warnings and per-run status; use new output paths to avoid stale files. |
See the [CLI reference](command-line-reference.md) for precise defaults,
timeouts, exit codes and recovery behavior.
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.