safer bridge mode

This commit is contained in:
ari committed 2026-09-23 19:29:28 -04:00
1 parent b5d59c34ac
commit d5afd6510f
7 files changed
+337 -120

No files matched your search

+65 -68
View File
@@ -483,89 +483,86 @@ auth in front of anything that isn't a toy, and keep the list short.
## Putting the guest directly on your LAN
The default setup puts the guest on an isolated bridge behind the host's NAT,
reachable from outside only through `publish`. This section is for when you
want the VM to be a first-class device on your LAN instead: its own address
from the LAN's DHCP, reachable on any port from any device on the network.
The default setup keeps the guest on an isolated bridge behind the host's
NAT, reachable from outside only through `publish`. This section is for
when you want the VM to be a first-class device on your LAN instead: its
own fixed address on the network, reachable on any port from any device,
while keeping everything it can see outbound locked down.
Enable it:
Enable it and tell it your LAN's numbers:
```nix
services.hermenix.network.bridged = true;
```
services.hermenix.network = {
bridged = true;
externalInterface = "enp191s0"; # your uplink (required)
In one sentence, what that does: the bridge absorbs your uplink
(`network.externalInterface`), the guest and the host share the LAN, the
guest takes a DHCP lease, and inbound traffic to the guest is open on every
port. Outbound is still gated by `lanAccess` / `allowLan`, and `hostAccess`
plus the host Nix cache still work over the service net at `10.77.0.1`.
### 1. Ready the guest first (one-time, if the image is older than this repo)
The guest keeps a static service-net address (`10.77.0.2/24`) for talking to
the host and adds DHCP on the same NIC, so one config works in both modes.
That is already what `guest/common.nix` does; if your guest image predates
it, apply the equivalent change to `/etc/nixos/common.nix` inside the VM:
```nix
systemd.network.networks."10-eth" = {
matchConfig.Type = "ether";
address = [ "10.77.0.2/24" ]; # service net to the host
routes = [ { Gateway = "10.77.0.1"; Metric = 200; } ]; # NAT-mode fallback
networkConfig.DHCP = "ipv4"; # LAN lease in bridged mode
dhcpV4Config = { # DHCP default route wins (100)
UseDNS = false;
RouteMetric = 100;
};
# Static LAN addressing: bridged mode does not use your LAN's DHCP.
lanAddress = "10.0.12.50"; # the guest's fixed LAN address
hostLanAddress = "10.0.12.10"; # this host's own LAN address
lanGateway = "10.0.12.1"; # your router
lanPrefixLength = 24; # default 24
# lanDns = [ "1.1.1.1" ]; # optional; defaults to lanGateway
};
```
`cd /etc/nixos && git apply -p1 < patch`, commit, and
`sudo nixos-rebuild switch --flake /etc/nixos#hermes`. In NAT mode the DHCP
attempt fails quietly (there is no server on the isolated bridge), so check
nothing broke: `ip -4 addr` still shows `10.77.0.2` and `ip route` still
goes via `10.77.0.1`.
What that gives you: the bridge absorbs the uplink, the host and the guest
share the LAN, and each side has a fixed address. The guest never needs to
know its own address - the module runs a small DHCP server on the bridge
that reserves `lanAddress` for the guest's MAC, so the VM stays a plain
DHCP client and just receives its address. This host keeps its LAN identity
too: the bridge clones your uplink's MAC, so the LAN sees this host under
its usual MAC (no duplicate-address surprises), and the guest's DHCP
broadcast never leaves the bridge, so nothing on your LAN can race the
reservation.
### 2. Rebuild the host with the toggle on
### What is and isn't reachable
Set `services.hermenix.network.bridged = true` alongside
`network.externalInterface`, then `sudo nixos-rebuild switch`. On rebuild
the host's uplink becomes a bridge port, the host takes a fresh DHCP lease
on the bridge, and the guest's DHCP is answered by the LAN router. The
network drops briefly while the host reconfigures - plan for it.
- **Inbound to the guest, from anywhere on the LAN: every port** is open.
The guest's own firewall decides what answers - by default it only opens
port 22, so the agent opens whatever it wants LAN-reachable.
- **Guest egress is still gated**, exactly as in NAT mode: `lanAccess`
entries and `allowLan` are unchanged. The VM sees the LAN, but only the
parts you have allowed.
- **Guest to host still works**: `hostAccess` and the host Nix cache are
reachable over the service net at `10.77.0.1` in both modes.
- **`publish` is ignored** in this mode - every inbound port is already
reachable. Drop the entries if you come back to NAT mode.
### 3. Verify
### Switching over
From the host, `hermenix vm ssh`. Inside the guest, `ip -4 addr` shows the
service net _and_ a LAN address, and `ip route` shows a default route via
your LAN gateway. From any other device on the LAN:
1. Pick three free addresses: the guest (`lanAddress`), this host
(`hostLanAddress` - use the address it already has on that interface,
e.g. a router reservation, so nothing else on the LAN breaks), and the
router itself (`lanGateway`). Keep `hostLanAddress` and `lanAddress`
outside any DHCP pool, or reserve them in the router first.
2. Set `network.bridged = true` with the options above, then
`sudo nixos-rebuild switch`. The network drops briefly while the host
reconfigures - plan for it.
3. Verify from the host: `hermenix vm ssh`; inside the guest,
`ip -4 addr` shows the service net (`10.77.0.2`) **and** its fixed LAN
address. From any other device on the LAN:
```bash
ssh hermes@<guest-lan-ip> # and any other port the guest opens
```
The guest's own firewall decides what answers - by default it only opens
port 22, so the agent must open whatever it wants LAN-reachable. Egress is
still gated too: from the guest, `192.168.1.50:11434` only works if it is
in `lanAccess` (or `allowLan = true`).
### Gotchas
- The LAN needs a working DHCP server.
- `publish` does nothing in this mode - every port is reachable, so its
entries are ignored. Drop them if you come back to NAT mode.
- The host's LAN IP comes from a fresh DHCP lease on the bridge, and the
bridge MAC can differ from the uplink's - the host's address may change
after the switch. Reserve it in the DHCP server if that matters.
- Any network config you had for the uplink interface is replaced by its
bridge-port role while bridged (this module's networkd unit for it takes
priority over most others).
```bash
ssh hermes@<guest-lan-address> # and any other port the guest opens
```
### Switching back
Set `bridged = false` and rebuild the host. The guest's DHCP client finds
no server on the isolated bridge and settles onto its static route via the
host again; no guest-side change needed.
Set `bridged = false` (the `lan*` options are ignored) and rebuild the
host. The guest's DHCP client finds no server on the isolated bridge and
settles onto its static route via the host again; no guest-side change
needed.
### Gotchas
- `hostLanAddress` is a static claim on the LAN - pick one your router
won't hand out, or reserve it.
- Any network config you had for the uplink interface is replaced by its
bridge-port role while bridged (this module's networkd unit for it takes
priority over most others).
- An older guest image that predates the DHCP-on-NIC setup in the current
`guest/common.nix` won't take an address in bridged mode; upgrade the
image or apply that config inside the VM first.
---