# Administrator Guide
Deployment, configuration, operations, and recovery for ndaal
CSAF-CRUD. For exhaustive key/flag descriptions see
[REFERENCE.md](../REFERENCE.md); for end-user workflows see the
[User Guide](User_Guide.md); for failure diagnosis see the
[Troubleshooting Guide](Troubleshooting_Guide.md).
## Overview
ndaal CSAF-CRUD is a single self-contained binary. It embeds two
databases (redb for CSAF documents, bundled SQLite for the audit log
and the user schema), generates its own TLS 1.3 certificate, and
needs no external services.
Two binaries ship from the workspace:
- `csaf-crud` — the web UI and JSON API server.
- `ndaal-csaf-cli` — a headless CLI for import, export, validate,
and stats.
## Platform support
- Minimum Rust toolchain: `1.93.0`, edition `2024`.
- Packaged targets: `x86_64-unknown-linux-gnu`,
`aarch64-unknown-linux-gnu`, `x86_64-apple-darwin`,
`aarch64-apple-darwin`, `aarch64-pc-windows-msvc`.
- Cross-compilation uses cargo-zigbuild.
## Installation
Build from source in the workspace root:
```bash
cargo build --release
# binaries: target/release/csaf-crud and target/release/ndaal-csaf-cli
```
To build without the optional OASIS validator and QUIC features
(smaller binary, fewer dependencies):
```bash
cargo build --release --no-default-features
```
## Configuration
The server reads a TOML file at startup. The path is the first
command-line argument and defaults to `config/default.toml`.
```bash
csaf-crud /etc/csaf-crud/config.toml
```
The shipped `config/default.toml`:
```toml
listen_addr = "127.0.0.1"
listen_port = 8180
data_dir = "./data"
# tls_cert = "config/cert.pem"
# tls_key = "config/key.pem"
```
Keys (full descriptions and the compiled-in fallbacks are in
[REFERENCE.md](../REFERENCE.md#configuration)):
- `listen_addr` — bind address. Default `127.0.0.1`. Set to `::` or
a routable address to expose the server beyond loopback (read the
security note below first).
- `listen_port` — TCP port for HTTP/1.1 and HTTP/2. The bundled
config uses `8180`; the QUIC/HTTP3 listener binds `listen_port + 1`
(UDP, `8181`).
- `data_dir` — directory holding `csaf.redb` and `csaf.sqlite`.
Created on first run if absent.
- `tls_cert` / `tls_key` — optional PEM paths. When unset, the
server generates a self-signed certificate at startup.
Operational settings (export directories, sidecar toggles,
publisher defaults, classification policy, CSAF mode) are **not** in
the TOML file. They live in redb and are edited at runtime through
the `/settings` page or `PUT /api/v1/settings`, and reset with
`POST /settings/reset`. See [REFERENCE.md](../REFERENCE.md#runtime-settings).
## TLS
- Transport is **TLS 1.3 only** (no TLS 1.2 fallback), via rustls
with the ring crypto provider — no OpenSSL or aws-lc.
- When no certificate is configured, the server issues a self-signed
certificate valid for **45 days** with SANs for `localhost`,
`127.0.0.1`, and `::1`. It is regenerated on every restart.
- For a stable certificate, set `tls_cert` and `tls_key` to PEM
files. Rotate them before expiry.
- Verify the deployed endpoints with the bundled harness
`test/testssl/run.sh`.
## Authentication and access control
This release enforces **no** authentication or authorization. Every
web page and API route is reachable by anyone who can connect. The
`users` and `sessions` tables exist in SQLite (Argon2id hashing,
per-user API keys) but are not yet enforced by the router.
Until authentication lands, operate the service accordingly:
- Keep `listen_addr = "127.0.0.1"` and reach it through an
authenticating reverse proxy or an SSH tunnel.
- Never expose it directly to an untrusted network.
- Restrict filesystem access to `data_dir` and the export/dump
directories — they hold every advisory and the audit log.
## Data directories
Created on first run relative to the working directory unless
reconfigured in settings:
| `data/` | `data_dir` | `csaf.redb` + `csaf.sqlite` |
| `data_import/` | `import_directory` | Inbox scanned by import |
| `data_export/` | `export_directory` | Exported CSAF + sidecars |
| `data_dump/` | `dump_directory` | Database snapshots |
| `data_log/` | `log_directory` | Rolling tracing logs |
## Running as a service
Example systemd unit (Linux):
```ini
[Unit]
Description=ndaal CSAF-CRUD
After=network.target
[Service]
ExecStart=/usr/local/bin/csaf-crud /etc/csaf-crud/config.toml
WorkingDirectory=/var/lib/csaf-crud
User=csaf
Environment=RUST_LOG=info
Restart=on-failure
[Install]
WantedBy=multi-user.target
```
Place the data directories under `WorkingDirectory` (or set absolute
paths in settings) so the service user owns them.
## Logging
- Logs are written to stderr and to a daily-rotated file
`<log_directory>/csaf-crud.log.<YYYY-MM-DD>`.
- The level is controlled by `RUST_LOG` (default `info`). Use
`RUST_LOG=debug` for verbose diagnosis; library noise from
`hyper`, `quinn`, and `h2` is filtered at `info`.
- If the log directory cannot be created, the server logs a warning
to stderr and continues with stderr-only logging.
## Audit log
Every create, update, delete, import, export, dump, and
settings-reset is recorded in the SQLite `audit_log` table. Export it
from `/admin/export` → Export Audit Log, or
`POST /api/v1/.../export-audit`, in Markdown, CSV, JSON, or
SARIF 2.1.0. Read it via `GET /api/v1/audit-log`.
## Backup and recovery
### Backup
Trigger a consistent snapshot from `/admin` → Dump Database (or
`POST /admin/dump`). It writes timestamped copies of both databases
plus the enabled hash sidecars to `dump_directory`:
```text
csaf.redb.<timestamp> + .sha-256 / .sha-512 / .sha3-512 / …
csaf.sqlite.<timestamp> + .sha-256 / .sha-512 / .sha3-512 / …
```
The redb snapshot is taken under a read transaction; the SQLite
snapshot uses the online backup API — both are consistent against
live traffic. Copy the `dump_directory` contents to off-host
storage on a schedule.
### Recovery
1. Stop the server.
2. Verify the snapshot integrity against its sidecar, for example
`shasum -a 512 -c csaf.sqlite.<timestamp>.sha-512`.
3. Copy `csaf.redb.<timestamp>` to `<data_dir>/csaf.redb` and
`csaf.sqlite.<timestamp>` to `<data_dir>/csaf.sqlite`. Remove any
stale `csaf.sqlite-wal` / `csaf.sqlite-shm` files.
4. Start the server; it opens the restored databases normally.
## Upgrades
1. Back up (dump) the databases first.
2. Replace the binary and restart.
3. SQLite migrations run automatically on open. redb and SQLite
schemas are forward-compatible within a minor series.
### In-place self-update
Both binaries can replace their own executable from the project's GitLab
releases. The capability is compiled into **every** build — it is never
behind a cargo feature — so there is exactly one binary shape to deploy,
and it is disabled by policy at runtime rather than by shipping a
different build.
```bash
# Is a newer release published? Never touches the running binary.
csaf-crud --check-update
ndaal-csaf-cli --check-update
# Download, verify against SHA256SUMS, and replace the running binary.
csaf-crud --self-update
```
Disable it on a package-managed or locked-down host:
```bash
csaf-crud --self-update --no-self-update # exit 3, nothing changed
export CSAF_NO_SELF_UPDATE=1 # same, for the whole host
```
`CSAF_NO_SELF_UPDATE` accepts `1`, `true`, `yes` or `on`
(case-insensitive); anything else, including an empty value, is treated
as "not set". An explicit `--no-self-update` on the command line always
wins over the environment. The policy gate is evaluated **before** any
network request is made, so a refused update produces no outbound
traffic.
| `0` | Up to date, update installed, host unreachable, `--help`, `--version` |
| `1` | `--self-update` failed: no asset for this triple, checksum mismatch, or install error |
| `2` | Argument parse error |
| `3` | `--self-update` refused by policy |
| `10` | `--check-update` found a newer release |
`--check-update` is safe to put in a boot path, a health check or a cron
job: it **never** fails on a network problem. An unreachable host, a
malformed API response, an empty release list and a rate-limit HTTP 403
all report `Unreachable` and exit `0`. Only exit `10` means "a newer
release exists", which is what lets a wrapper branch on it without
parsing text:
```bash
if csaf-crud --check-update; then
logger "csaf-crud is current"
else
[ $? -eq 10 ] && logger "csaf-crud update available"
fi
```
When the server binary updates itself, the new executable takes effect on
the **next restart** — an already-running process keeps executing the
image it started with. Under systemd, follow `--self-update` with
`systemctl restart`.
#### What the verification does and does not prove
The downloaded archive is checked against the `SHA256SUMS` manifest
published in the same release. That proves the artifact matches the
manifest and was neither corrupted in transit nor swapped for another
asset within the release.
It is **not a signature**. Anyone able to rewrite the release archive at
the source can rewrite `SHA256SUMS` alongside it. This is **integrity,
not authenticity**, and the artifacts are **not signed** — detached
signing is deliberately not enabled rather than half-implemented, because
a partial signing story invites false confidence.
Note also that GitLab's releases API publishes no per-asset digest, so
the updater's automatic release-digest check is a no-op on this backend;
the `SHA256SUMS` manifest is the only integrity check that actually runs.
Operators who need authenticity should disable self-update
(`CSAF_NO_SELF_UPDATE=1`), install from the release bundle by hand, and
verify the five checksum sidecars (`.sha-256`, `.sha-512`, `.sha3-512`,
`.blake3-512`, `.shake256-512`) out of band.
## Verification
After deployment, confirm the service is healthy:
```bash
curl -k https://127.0.0.1:8180/api/v1/system/health
# {"data":{"status":"healthy", ...}, "_links": {...}}
```
`-k` is required while the self-signed certificate is in use.