docs: add config.md reference for the daemon TOML schema
README previously punted on the config schema with a "full key list in internal/config/config.go" pointer. New docs/config.md walks every TOML key the daemon reads — top-level, [vm_defaults], [[file_sync]] — with type, default, and a one-sentence description per row, plus a copy-pasteable example at the bottom. Sourced 1:1 from internal/config/config.go's fileConfig (and the defaults in load() + internal/model/types.go), so it stays accurate as long as those structs are the schema source of truth. README's existing config section now points at docs/config.md, and the "Further reading" list gets it as the first bullet. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
7d7c15a370
commit
45826f0db0
2 changed files with 155 additions and 1 deletions
|
|
@ -211,7 +211,7 @@ Most commonly set:
|
|||
paths are rejected at config load.
|
||||
- `firecracker_bin` — override the auto-resolved `PATH` lookup.
|
||||
|
||||
Full key list in `internal/config/config.go`.
|
||||
Full key reference: [`docs/config.md`](docs/config.md).
|
||||
|
||||
### `vm_defaults` — sizing for new VMs
|
||||
|
||||
|
|
@ -293,6 +293,7 @@ guest IPs to an untrusted network.
|
|||
|
||||
## Further reading
|
||||
|
||||
- [`docs/config.md`](docs/config.md) — full config key reference.
|
||||
- [`docs/dns-routing.md`](docs/dns-routing.md) — resolving
|
||||
`<vm>.vm` hostnames from the host.
|
||||
- [`docs/image-catalog.md`](docs/image-catalog.md) — bundle format
|
||||
|
|
|
|||
153
docs/config.md
Normal file
153
docs/config.md
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
# Config reference
|
||||
|
||||
banger reads `~/.config/banger/config.toml` at daemon start; every key is
|
||||
optional. Defaults are applied for anything you omit. Path: see also
|
||||
[docs/privileges.md](privileges.md) > Filesystem mutations.
|
||||
|
||||
---
|
||||
|
||||
## Top-level keys
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `log_level` | string | `"info"` | Daemon log verbosity; overridden at runtime by `BANGER_LOG_LEVEL`. Accepted values are the standard slog levels: `debug`, `info`, `warn`, `error`. |
|
||||
| `firecracker_bin` | string | auto-detected from `PATH` | Path to the `firecracker` binary. Accepts absolute paths or `~/`-anchored paths. If unset, banger resolves `firecracker` on `PATH` at startup. |
|
||||
| `jailer_bin` | string | `"/usr/bin/jailer"` | Path to the Firecracker `jailer` binary used to sandbox each VM process. |
|
||||
| `jailer_enabled` | bool | `true` | When `false`, VMs are launched directly without the jailer. Disabling the jailer removes the seccomp/namespace sandbox; only for debugging or environments where jailer is unavailable. |
|
||||
| `jailer_chroot_base` | string | `"<state_dir>/jail"` | Base directory under which the jailer creates per-VM chroot trees. Must be on the same filesystem as the image store to allow hard-linking without crossing device boundaries. |
|
||||
| `ssh_key_path` | string | `"<state_dir>/ssh/id_ed25519"` (auto-generated) | Host SSH key used to reach guest VMs. Accepts absolute paths or `~/`-anchored paths; `~/foo` expands against `$HOME`. Relative paths are rejected. If unset, banger auto-generates an ed25519 keypair on first start. |
|
||||
| `default_image_name` | string | `"debian-bookworm"` | Image used when `--image` is omitted from `vm run` / `vm create`. The named image is auto-pulled from the catalog if not already local. |
|
||||
| `auto_stop_stale_after` | duration | `"0"` (disabled) | If non-zero, the daemon automatically stops VMs that have not been touched within this duration. Accepts Go duration strings (`"24h"`, `"2h30m"`). |
|
||||
| `stats_poll_interval` | duration | `"10s"` | How often the daemon collects CPU and memory stats for running VMs. Accepts Go duration strings (`"30s"`, `"1m"`). |
|
||||
| `bridge_name` | string | `"br-fc"` | Name of the Linux bridge device banger creates for the VM network. |
|
||||
| `bridge_ip` | string | `"172.16.0.1"` | IP address assigned to the host side of the bridge (the gateway VMs see). |
|
||||
| `cidr` | string | `"24"` | Prefix length for the VM subnet (combined with `bridge_ip` to define the network, e.g. `172.16.0.0/24`). |
|
||||
| `tap_pool_size` | int | `4` | Number of TAP network devices pre-allocated in the pool. Increase if you routinely run more concurrent VMs than this value. |
|
||||
| `default_dns` | string | `"1.1.1.1"` | DNS resolver address advertised to guest VMs via DHCP. |
|
||||
|
||||
---
|
||||
|
||||
## `[vm_defaults]`
|
||||
|
||||
The optional `[vm_defaults]` block sets the sizing floor for every new VM.
|
||||
When a key is omitted (or zero), banger falls back to host-derived heuristics
|
||||
and then to built-in constants. `banger doctor` prints the effective defaults
|
||||
with their provenance.
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `vcpu` | int | host heuristic (≈ `cpus/4`, max 4) | Number of vCPUs assigned to each new VM. Must be ≥ 0; 0 means "let banger decide." |
|
||||
| `memory_mib` | int | host heuristic (≈ `ram/8`, max 8192) | RAM in mebibytes assigned to each new VM. Must be ≥ 0; 0 means "let banger decide." |
|
||||
| `disk_size` | string | `"8G"` | Size of the per-VM work disk. Accepts K/M/G suffixes (`"16G"`, `"512M"`). Maximum is 128 GiB. |
|
||||
| `system_overlay_size` | string | `"8G"` | Size of the copy-on-write overlay layered over the read-only root filesystem. Accepts K/M/G suffixes. Maximum is 128 GiB. |
|
||||
|
||||
---
|
||||
|
||||
## `[[file_sync]]`
|
||||
|
||||
Each `[[file_sync]]` entry copies a file or directory from the host into
|
||||
the VM's work disk at `vm create` time. You may declare any number of
|
||||
entries; the default is none. Missing host paths are skipped with a warning
|
||||
rather than failing the create.
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `host` | string | **required** | Source path on the host. Must be absolute or `~/`-anchored, and must resolve inside the installed owner's home directory. Top-level symlinks are followed only when their target stays inside that home. |
|
||||
| `guest` | string | **required** | Destination path inside the VM. Must be absolute or `~/`-anchored, and must resolve under `/root` (the work disk mount point). |
|
||||
| `mode` | string | `"0600"` for files, `"0755"` for directories | Unix permission bits applied to the destination. Must be a 3- or 4-digit octal string (`"0755"`, `"600"`). |
|
||||
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
A fully annotated `config.toml` showing every section. Omit any key to keep
|
||||
the built-in default.
|
||||
|
||||
```toml
|
||||
# ~/.config/banger/config.toml
|
||||
|
||||
# ── Binaries ──────────────────────────────────────────────────────────────────
|
||||
|
||||
# Override the auto-resolved firecracker binary.
|
||||
# firecracker_bin = "/usr/local/bin/firecracker"
|
||||
|
||||
# Override the default jailer binary path.
|
||||
# jailer_bin = "/usr/bin/jailer"
|
||||
|
||||
# Disable the jailer (removes seccomp/namespace sandbox — debug only).
|
||||
# jailer_enabled = false
|
||||
|
||||
# Base directory for per-VM jailer chroot trees.
|
||||
# jailer_chroot_base = "/var/lib/banger/jail"
|
||||
|
||||
# ── Identity ──────────────────────────────────────────────────────────────────
|
||||
|
||||
# SSH key used to reach VMs. Auto-generated as an ed25519 key if unset.
|
||||
# ssh_key_path = "~/.local/state/banger/ssh/id_ed25519"
|
||||
|
||||
# Default image for `vm run` / `vm create` when --image is omitted.
|
||||
# default_image_name = "debian-bookworm"
|
||||
|
||||
# ── Logging ───────────────────────────────────────────────────────────────────
|
||||
|
||||
# Daemon log verbosity: debug | info | warn | error
|
||||
# log_level = "info"
|
||||
|
||||
# ── Lifecycle ─────────────────────────────────────────────────────────────────
|
||||
|
||||
# Automatically stop VMs not touched within this window. 0 disables auto-stop.
|
||||
# auto_stop_stale_after = "24h"
|
||||
|
||||
# How often to collect CPU/memory stats for running VMs.
|
||||
# stats_poll_interval = "10s"
|
||||
|
||||
# ── Networking ────────────────────────────────────────────────────────────────
|
||||
|
||||
# Name of the Linux bridge device created for the VM network.
|
||||
# bridge_name = "br-fc"
|
||||
|
||||
# Host-side IP address of the bridge (the gateway VMs see).
|
||||
# bridge_ip = "172.16.0.1"
|
||||
|
||||
# Subnet prefix length combined with bridge_ip.
|
||||
# cidr = "24"
|
||||
|
||||
# TAP device pool size — increase if you run more concurrent VMs than this.
|
||||
# tap_pool_size = 4
|
||||
|
||||
# DNS resolver advertised to guests.
|
||||
# default_dns = "1.1.1.1"
|
||||
|
||||
# ── VM sizing defaults ────────────────────────────────────────────────────────
|
||||
|
||||
[vm_defaults]
|
||||
# vCPUs per VM. 0 = let banger decide from host heuristics.
|
||||
vcpu = 2
|
||||
|
||||
# RAM in MiB per VM. 0 = let banger decide from host heuristics.
|
||||
memory_mib = 2048
|
||||
|
||||
# Work disk size (K/M/G suffix). Max 128G.
|
||||
disk_size = "8G"
|
||||
|
||||
# Copy-on-write overlay over the root filesystem (K/M/G suffix). Max 128G.
|
||||
system_overlay_size = "8G"
|
||||
|
||||
# ── Host → guest file copies ──────────────────────────────────────────────────
|
||||
|
||||
# Copy an entire directory (recursive).
|
||||
[[file_sync]]
|
||||
host = "~/.aws"
|
||||
guest = "~/.aws"
|
||||
|
||||
# Copy a single file with explicit permissions.
|
||||
[[file_sync]]
|
||||
host = "~/.config/gh/hosts.yml"
|
||||
guest = "~/.config/gh/hosts.yml"
|
||||
|
||||
# Copy a script and make it executable.
|
||||
[[file_sync]]
|
||||
host = "~/bin/my-script"
|
||||
guest = "~/bin/my-script"
|
||||
mode = "0755"
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue