124 lines
4.4 KiB
Markdown
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.
|