68 lines
5.4 KiB
Markdown
68 lines
5.4 KiB
Markdown
# Administration API and configuration automation
|
|
|
|
RustProxy exposes an authenticated administration API on the **separate administration listener** (normally `127.0.0.1:9090`). Open **`/docs → API`** after signing in to view the bundled OpenAPI/Swagger schema, including request bodies and available actions. That schema is the endpoint reference; server validation remains authoritative.
|
|
|
|
## Selected API endpoints
|
|
|
|
The current bundled `src/admin/openapi.json` declares these operations (among others):
|
|
|
|
| Method and path | Purpose |
|
|
|---|---|
|
|
| `GET /healthz` | Minimal health response, without privileged state. |
|
|
| `GET /api/auth/status` | Whether first-time administrator setup is required. |
|
|
| `POST /api/auth/login` · `POST /api/auth/logout` | Start/end a browser admin session. |
|
|
| `GET /api/auth/session` | Validate current admin session. |
|
|
| `GET /api/config` · `PUT /api/config` | Read or replace validated, revisioned configuration. GET also returns read-only `storage` metadata (SQLite/JSON source and paths). |
|
|
| `POST /api/config/reload` | Revalidate and hot-reload manually changed `--config` JSON; revision-aware. |
|
|
| `GET/POST /api/api-tokens` · `DELETE /api/api-tokens/{id}` | List/generate/revoke general RO/RW API tokens (browser-admin-only). |
|
|
| `GET/POST/DELETE /api/prometheus-token` | Inspect/generate/rotate/revoke a standalone Prometheus scrape token (browser-admin-only). |
|
|
| `PUT /api/config/{section}` | Update one supported configuration section. |
|
|
| `GET /api/config/history` · `POST /api/config/history/restore` | Review/restore retained configuration snapshots. |
|
|
| `GET /api/status` · `GET /api/backends` | Operational status and backend observations. |
|
|
| `GET /api/cache` · `POST /api/cache/purge` · `POST /api/cache/invalidate` | Cache observations and authenticated invalidation. |
|
|
| `GET /api/logs` · `GET /api/live-logs` | Recent and streaming request logs. |
|
|
| `GET /api/file-logs` · `GET /api/file-logs/query` | Stored-log exploration. |
|
|
| `GET /api/traffic` · `GET /api/system-info` | Traffic and system observations. |
|
|
| `GET /api/docker` · `POST /api/docker/refresh` | Docker-agent observation and refresh. |
|
|
| `GET /api/certificates` · `POST /api/certificates/upload` | Certificate inventory/import. |
|
|
| `GET /api/acme` · `POST /api/acme/issue` · `POST /api/acme/renew` | Managed certificate jobs. |
|
|
| `GET/PUT /api/preferences` | Personal UI settings. |
|
|
| `GET /api/dashboard-presets` and named preset operations | Saved Overview presets. |
|
|
| `GET /docs/openapi.json` | Protected machine-readable API specification. |
|
|
|
|
Some paths have additional DELETE/PATCH operations, job-status resources, query parameters or restricted actions. Use OpenAPI for the **actual fields/methods**, not guesses based on a table. `GET /metrics` here is not a replacement for the separate Prometheus exporter.
|
|
|
|
## Authentication and safe writes
|
|
|
|
- Ordinary API calls require an administrator browser/session cookie on the admin listener, or a scoped general API Bearer token for explicitly allowlisted API methods/paths. Logging in also provides CSRF context. Writes require correct Host/Origin, `X-CSRF-Token` and `X-RustProxy-Request: 1` as enforced by the server.
|
|
- The Swagger **API** tab uses the signed-in session. Read calls can be executed; mutations require explicit confirmation. It cannot bypass server-side authorization.
|
|
- Configuration writes are revisioned (`expected_revision`) and rejected if based on a stale save. `GET /api/config` returns `{revision, config, storage}`; `storage` is runtime metadata and must not be copied inside the editable `config` object or included as a write parameter. PUT and history-restore responses remain `{revision, config}`. Prefer section updates over replacing the entire document when practical.
|
|
- `/docs`, API schemas, configuration, logs, certificates and most observations are **not anonymous**. Keep the listener restricted and use HTTPS or a tunnel for remote access.
|
|
|
|
## Local CLI alternatives
|
|
|
|
The included `rust-proxy` program supports configuration and backup operations without turning browser sessions into automation tokens:
|
|
|
|
```bash
|
|
rust-proxy --data-dir /var/lib/rustproxy config get
|
|
rust-proxy --data-dir /var/lib/rustproxy config validate config.json
|
|
rust-proxy --data-dir /var/lib/rustproxy config apply config.json
|
|
rust-proxy --data-dir /var/lib/rustproxy config reload
|
|
rust-proxy --data-dir /var/lib/rustproxy backup create --output /private/site.rpb
|
|
```
|
|
|
|
Run CLI commands as an authorized local operator with the correct private data directory. The `admin` subcommands provide first setup, password recovery, session revocation and status; `tls` supports certificate generate/import/deploy/reload. Run `rust-proxy --help` for exact options.
|
|
|
|
## Restricted Certificate API credentials
|
|
|
|
**Settings → Certificate API** can create credentials containing a **Key ID + Bearer token** with explicit certificate-ID grants. New keys default to reload-only; deploy permission is separate. The clear token is displayed at creation/rotation and is not a general admin API token.
|
|
|
|
An authorized client sends:
|
|
|
|
```text
|
|
Authorization: Bearer <secret>
|
|
X-RustProxy-Certificate-Key: <key-id>
|
|
```
|
|
|
|
The credential can be used only for allowed certificate reload/deploy operations, not configuration, users, metrics or secret management. Non-loopback use requires the appropriate administration HTTPS security boundary. Rotate broad or legacy credentials. See [API access](API_ACCESS.md) and [Certificates](ACME_PROVIDERS.md).
|