From 45826f0db029d2268239c9934cc8b4d4394b7880 Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Tue, 28 Apr 2026 15:11:18 -0300 Subject: [PATCH] docs: add config.md reference for the daemon TOML schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- README.md | 3 +- docs/config.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 1 deletion(-) create mode 100644 docs/config.md diff --git a/README.md b/README.md index 96d801b..69a43d4 100644 --- a/README.md +++ b/README.md @@ -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` hostnames from the host. - [`docs/image-catalog.md`](docs/image-catalog.md) — bundle format diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..ad980b2 --- /dev/null +++ b/docs/config.md @@ -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 | `"/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 | `"/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" +```