20260914 强制 TOML 配置并完善 TA 刷新与 daemon
This commit is contained in:
@@ -1,140 +1,127 @@
|
||||
# Command-line reference
|
||||
|
||||
This reference covers v0.1.0. `panda-rpki --help` displays version and usage;
|
||||
there is no separate `--version` option.
|
||||
For every field, default, constraint and complete example, see the [TOML configuration reference](configuration.md)。
|
||||
|
||||
## Syntax
|
||||
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 validate --tal FILE --ta FILE --out DIRECTORY [OPTIONS]
|
||||
panda-rpki daemon --state-root DIRECTORY [DAEMON OPTIONS] -- [VALIDATION OPTIONS]
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Inputs and outputs
|
||||
## TOML schema
|
||||
|
||||
| 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`. |
|
||||
Every file contains `config-version = 1` and a matching `mode` value:
|
||||
|
||||
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.
|
||||
```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
|
||||
|
||||
## State and network
|
||||
[[anchors]]
|
||||
id = "ripe"
|
||||
tal = "input/ripe.tal"
|
||||
ta = "input/ripe.cer" # omit for automatic refresh from the TAL URI
|
||||
constraints = "input/ripe.constraints"
|
||||
```
|
||||
|
||||
| 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. |
|
||||
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.
|
||||
|
||||
| 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. |
|
||||
The remaining common keys and defaults are:
|
||||
|
||||
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.
|
||||
| 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` |
|
||||
|
||||
RRDP references and redirects enforce HTTPS and same-origin rules. Extra
|
||||
trust roots do not relax origin checks. No separate rsync timeout is exposed.
|
||||
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.
|
||||
|
||||
## Workers and queues
|
||||
## Inspection and outcomes
|
||||
|
||||
| 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)`. |
|
||||
`--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.
|
||||
|
||||
All values must be positive. Budgets are shared across TALs. Higher concurrency
|
||||
can increase memory consumption and does not guarantee proportional speedup.
|
||||
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`:
|
||||
|
||||
## Logging
|
||||
| Status | Default exit | `require-complete = true` |
|
||||
| --- | ---: | ---: |
|
||||
| success | 0 | 0 |
|
||||
| partial | 0 | 3 |
|
||||
| failed | 2 | 2 |
|
||||
|
||||
| Option | Default | Values |
|
||||
| --- | --- | --- |
|
||||
| `--log-level <level>` | `info` | `off`, `error`, `warn`, `info`, `debug`, `trace` |
|
||||
| `--log-progress-interval-secs <seconds>` | `10` | Periodic progress; `0` disables periodic events, not stage events. CLI overrides `PANDA_RPKI_LOG_PROGRESS_INTERVAL_SECS`. |
|
||||
| `--log-format <format>` | `text` | `text`, `json` |
|
||||
`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.
|
||||
|
||||
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.
|
||||
With `publish-dir`, only a complete success is copied to an immutable run:
|
||||
|
||||
Other `PANDA_RPKI_*` variables in [Compose](docker.md) are template substitutions,
|
||||
not configuration variables read directly by the binary.
|
||||
```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
|
||||
```
|
||||
|
||||
## Daemon
|
||||
`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.
|
||||
|
||||
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 `--`.
|
||||
## Configuration lifecycle
|
||||
|
||||
| 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`,
|
||||
`process-output.txt`, `validator.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.
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user