Files

124 lines
4.4 KiB
Markdown

# Network
Default model and reachability table: [CONCEPTS.md](CONCEPTS.md#the-boundary-is-the-host).
## Mode matrix
| | NAT (default) | Bridged (`network.bridged = true`) |
| ------------------------------ | ------------------------------------- | ---------------------------------------- |
| Guest address | `10.77.0.2` on isolated bridge | service net **plus** fixed LAN address |
| Inbound from LAN / internet | only via `publish` | every port the guest opens |
| Guest → public internet | yes (masqueraded) | yes (L2 / LAN gateway) |
| Guest → private LAN | `lanAccess` / `allowLan` only | same gates |
| Guest → host services | `hostAccess` + host cache on `10.77.0.1` | same over service net |
| `publish` | DNAT on uplink | **ignored** |
## Guest → a service on your LAN
```nix
services.hermenix.lanAccess = [
{ address = "192.168.1.50"; port = 11434; } # ollama
{ address = "192.168.1.50"; port = 9000; proto = "udp"; }
];
```
One destination:port per entry, punched through the RFC1918 drop. Traffic is
masqueraded; the peer sees the host's address.
`allowLan = true` opens all private space at once. Prefer `lanAccess` — an
agent that goes wrong should not wander.
## Guest → a service on the host
```nix
services.hermenix.hostAccess = [ { port = 8188; } ];
```
The service must bind somewhere the guest can see. `127.0.0.1` will not work
(guest arrives on the bridge). Bind to `10.77.0.1` (bridge only) or
`0.0.0.0`:
```nix
services.comfyui.listenAddress = "10.77.0.1";
```
From the guest: `http://10.77.0.1:8188`.
Often better than GPU passthrough when you only need the capability over HTTP
— see [PASSTHROUGH.md](PASSTHROUGH.md).
## Expose a guest service
**Guest side** — agent opens its firewall in `/etc/nixos`:
```nix
networking.firewall.allowedTCPPorts = [ 22 8080 ];
```
**Host only** — already allowed (outbound host→guest):
```bash
curl http://10.77.0.2:8080
```
**Wider network** (NAT mode):
```nix
services.hermenix.publish = [
{ hostPort = 8080; guestPort = 8080; }
];
```
DNATs the uplink port and opens the forward rule. Ports need not match.
A published port only answers on the host's own addresses (LAN, tailscale, and
so on). Traffic to other addresses the host routes for, such as containers with
their own LAN IPs, is left alone.
Publishing is the one change that lets the outside world start conversations
with the agent's machine — put TLS/auth in front of anything that isn't a toy.
## Bridged mode (guest on the LAN)
Guest becomes a first-class LAN device: fixed address, reachable on any port it
opens, outbound still gated.
```nix
services.hermenix.network = {
bridged = true;
externalInterface = "enp191s0";
lanAddress = "10.0.12.50"; # guest's fixed LAN address
hostLanAddress = "10.0.12.10"; # this host's LAN address
lanGateway = "10.0.12.1";
lanPrefixLength = 24;
# lanDns = [ "1.1.1.1" ]; # optional; defaults to lanGateway
};
```
The bridge absorbs the uplink. The host-side DHCP on the bridge reserves
`lanAddress` for the guest MAC; the guest stays a plain DHCP client. The
bridge clones the uplink MAC so the host keeps its LAN identity. Guest DHCP
broadcast never leaves the bridge.
### Switching over
1. Pick free addresses for guest, host (use the host's existing LAN address if
reserved), and gateway. Keep them outside the DHCP pool or reserve them.
2. Set options above, `sudo nixos-rebuild switch` (brief network drop).
3. Verify: `hermenix vm ssh`; inside, `ip -4 addr` shows `10.77.0.2` **and**
the LAN address. From another LAN device:
`ssh hermes@<guest-lan-address>`.
### Switching back
`bridged = false` and rebuild. Guest DHCP finds no server on the isolated
bridge and falls back to the static route via the host. No guest-side change.
### Gotchas
- `hostLanAddress` is a static LAN claim — reserve it.
- Uplink network config is replaced by the bridge-port role while bridged.
- Older guest images without DHCP-on-NIC in `guest/common.nix` won't take a
bridged address; upgrade the image or apply that config inside the VM first.
- Drop `publish` entries if you return to NAT mode; they do nothing while
bridged.