# 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.