Thales Maciel
88425fb857
Adds docs/dns-routing.md covering how `<vm>.vm` resolution works: auto-configuration on systemd-resolved hosts (what the daemon already does), and per-resolver recipes for dnsmasq / NetworkManager+dnsmasq / /etc/resolv.conf / macOS `/etc/resolver/` / WSL. Plus verification via `dig @127.0.0.1 -p 42069` and troubleshooting for the common failure modes. README reshape: lead with the three things a common user needs — quick start, what `vm run` does, where to put hostnames + image + config — and push the rest to docs. `vm create` / OCI `image pull` / `image register` / workspace-and-session primitives are all still documented, just under docs/advanced.md where they're not in the first-time reader's way. Web UI and unnecessary implementation notes dropped; the "further reading" section at the bottom enumerates the five docs pages so nothing becomes hard to find. README shrinks from 208 → 158 lines. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
# DNS routing — resolving `<vm>.vm` hostnames from the host
|
|
|
|
banger's daemon runs a local DNS server on `127.0.0.1:42069` that
|
|
answers queries under the `.vm` zone. Every VM you create gets a
|
|
record:
|
|
|
|
```
|
|
devbox.vm → 172.16.0.9 (whatever guest IP it was assigned)
|
|
```
|
|
|
|
With that plus host-side DNS routing, you can:
|
|
|
|
```bash
|
|
ssh root@devbox.vm
|
|
curl http://devbox.vm:3000
|
|
```
|
|
|
|
from anywhere on the host without copy-pasting guest IPs.
|
|
|
|
## systemd-resolved hosts — nothing to configure
|
|
|
|
If your host uses `systemd-resolved` (most modern Linux desktops —
|
|
Ubuntu ≥18.04, Fedora, Arch with the service enabled), banger
|
|
auto-wires it. On daemon start it runs:
|
|
|
|
```
|
|
sudo resolvectl dns <bridge> 127.0.0.1:42069
|
|
sudo resolvectl domain <bridge> ~vm
|
|
sudo resolvectl default-route <bridge> no
|
|
```
|
|
|
|
against the banger bridge (`br-fc` by default). systemd-resolved
|
|
routes only `.vm` lookups to banger's DNS; everything else goes to
|
|
your normal upstream. No other changes needed.
|
|
|
|
Verify: `resolvectl status br-fc` should list `127.0.0.1:42069` under
|
|
**Current DNS Server** and `~vm` under **DNS Domain**.
|
|
|
|
`banger daemon stop` reverts the bridge's resolvectl state on shutdown.
|
|
|
|
## Non-systemd-resolved hosts
|
|
|
|
banger detects `resolvectl`'s absence and skips the auto-wire. You
|
|
configure your own resolver. Below are recipes for the common cases.
|
|
|
|
In every case the goal is the same: **route `.vm` queries to
|
|
`127.0.0.1` port `42069`, leave everything else alone**.
|
|
|
|
### dnsmasq
|
|
|
|
Add a stanza to your dnsmasq config (e.g.
|
|
`/etc/dnsmasq.d/banger-vm.conf`):
|
|
|
|
```
|
|
server=/vm/127.0.0.1#42069
|
|
```
|
|
|
|
Reload dnsmasq (`sudo systemctl reload dnsmasq` or equivalent) and
|
|
test:
|
|
|
|
```
|
|
dig devbox.vm
|
|
```
|
|
|
|
### NetworkManager with dnsmasq plugin
|
|
|
|
Same file as above; NetworkManager picks it up automatically if it's
|
|
configured to use the dnsmasq plugin (`dns=dnsmasq` in
|
|
`/etc/NetworkManager/NetworkManager.conf`). Restart NetworkManager
|
|
after editing.
|
|
|
|
### Raw `/etc/resolv.conf`
|
|
|
|
If you edit `resolv.conf` directly, there's no per-domain routing —
|
|
you'd have to point ALL DNS through banger, which you probably don't
|
|
want. Install `dnsmasq` instead and use the stanza above.
|
|
|
|
### macOS (if you ever run banger on a Linux VM hosted on macOS)
|
|
|
|
macOS supports per-TLD resolvers out of the box. Create
|
|
`/etc/resolver/vm` (as root):
|
|
|
|
```
|
|
nameserver 127.0.0.1
|
|
port 42069
|
|
```
|
|
|
|
No daemon reload needed — `scutil --dns` should list `.vm` under
|
|
"Resolver configurations" immediately.
|
|
|
|
### Windows/WSL
|
|
|
|
WSL2 inherits the Windows resolver by default and cannot be told to
|
|
route `.vm` anywhere. Options:
|
|
|
|
1. Run banger inside WSL but resolve manually: `ssh root@172.16.0.9`.
|
|
2. Set up `dnsmasq` on the WSL distro and point its resolv.conf at
|
|
it; then follow the dnsmasq recipe above.
|
|
|
|
## Verifying the DNS server
|
|
|
|
Regardless of host-side routing, you can always query banger's DNS
|
|
server directly:
|
|
|
|
```bash
|
|
dig @127.0.0.1 -p 42069 devbox.vm
|
|
```
|
|
|
|
Returns the guest IP if the VM is running. If it returns NXDOMAIN,
|
|
the VM either doesn't exist under that name or isn't running yet.
|
|
|
|
`banger vm list` shows the VM names banger knows about.
|
|
|
|
## Troubleshooting
|
|
|
|
- **`resolvectl` errors about "system has not been booted with systemd
|
|
as init system"** — you're probably inside a container. banger's
|
|
DNS still works; set up your resolver manually.
|
|
- **Port 42069 already in use** — another daemon is bound there
|
|
(previous banger instance not shut down cleanly, or an unrelated
|
|
app). `ss -ulpn | grep 42069` shows who. `banger daemon stop`
|
|
cleans up banger's own listener.
|
|
- **`devbox.vm` resolves but SSH hangs** — DNS is fine; the VM
|
|
might not be up yet or the bridge NAT is misconfigured.
|
|
`banger vm ssh devbox` uses the guest IP directly and bypasses
|
|
DNS — try that to isolate.
|
|
- **Changes to `default_dns` don't affect `.vm` resolution** —
|
|
`default_dns` is the upstream the GUEST uses; it's unrelated to
|
|
host-side `.vm` routing.
|
|
|
|
## Port and bridge tuning
|
|
|
|
| Setting | Default | Notes |
|
|
|---|---|---|
|
|
| DNS listen addr | `127.0.0.1:42069` | Not configurable in v1. Edit `internal/vmdns/server.go` if you really need to change it. |
|
|
| Bridge name | `br-fc` | Configurable via `bridge_name` in `~/.config/banger/config.toml`. |
|
|
| Bridge IP | `172.16.0.1` | Configurable via `bridge_ip`. |
|
|
| Resolver route domain | `~vm` | Not configurable. |
|