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

+200 -25
View File
@@ -38,11 +38,36 @@ let
# Netfilter mark tagging guest-originated traffic in bridged mode. The
# guest's only way in is the tap interface, so marking at the bridge
# prerouting hook is as specific as an address match - and it is the only
# way to identify the guest at the ip-family layer, where its DHCP-issued
# LAN address is not statically known. 18501 == 0x4845 ("HE"), for hermenix.
# prerouting hook identifies the guest regardless of which address it
# currently presents - its static service-net address, or the fixed LAN
# address served to it by the host-side DHCP on the bridge. 18501 ==
# 0x4845 ("HE"), for hermenix.
bridgeMark = 18501;
# Dotted-quad netmask for a prefix length, used by the bridged-mode DHCP
# server's single-address lease (dnsmasq needs an explicit mask for a
# one-address range).
netmaskFromPrefix =
p:
lib.concatStringsSep "." (
lib.genList (
b:
toString (
builtins.elemAt [
0
128
192
224
240
248
252
254
255
] (lib.max 0 (lib.min 8 (p - b * 8)))
)
) 4
);
# Graceful ACPI power button via QMP, then wait for QEMU to exit.
stopScript = pkgs.writeShellScript "hermes-vm-stop" ''
set -eu
@@ -337,24 +362,68 @@ in
type = types.int;
default = 24;
};
lanAddress = mkOption {
type = types.str;
default = "";
example = "10.0.12.50";
description = "The guest's fixed address on your LAN. Required when `bridged = true`.";
};
hostLanAddress = mkOption {
type = types.str;
default = "";
example = "10.0.12.10";
description = ''
This host's own address on your LAN. When `bridged` is enabled the
uplink becomes a bridge port and this address moves onto the bridge
(which clones the uplink's MAC, so the host keeps its LAN identity).
Required when `bridged = true`.
'';
};
lanGateway = mkOption {
type = types.str;
default = "";
example = "10.0.12.1";
description = ''
Your LAN's router. Used as the default gateway for the guest and,
while `bridged`, for this host's bridge too (DNS unless `lanDns` is
set). Required when `bridged = true`.
'';
};
lanPrefixLength = mkOption {
type = types.int;
default = 24;
description = "Prefix length of your LAN subnet (netmask).";
};
lanDns = mkOption {
type = types.listOf types.str;
default = [ ];
example = [ "1.1.1.1" ];
description = ''
DNS servers for this host while `bridged` (the bridge no longer
takes a DHCP lease). Defaults to the LAN gateway.
'';
};
bridged = mkOption {
type = types.bool;
default = false;
description = ''
Put the guest directly on your LAN instead of behind the host's
NAT. The bridge absorbs `externalInterface`, and the guest takes
an address from your LAN's DHCP, so any device on the LAN can
reach any port the guest exposes.
NAT. The bridge absorbs `externalInterface`, so any device on the
LAN can reach any port the guest exposes.
Addressing is fully static - no DHCP is involved. You must give
the guest a fixed LAN address (`lanAddress`), the host's own LAN
address (`hostLanAddress` - it moves onto the bridge), and the
LAN gateway (`lanGateway`). The guest is handed `lanAddress` by a
DHCP server this module runs on the bridge, keyed to the guest's
MAC (`network.mac`), so the guest itself stays a plain DHCP
client and never needs to know its own address.
Inbound is no longer limited to `publish` (which is ignored in
this mode): the LAN may reach every guest port. Outbound is still
governed by `lanAccess` / `allowLan`, and `hostAccess` plus the
host cache still work over the host-guest service net
(`hostAddress` stays configured on the bridge).
Requires a working DHCP server on the LAN, and a guest that runs
a DHCP client on its NIC (see guest/common.nix - this repo's
guest does).
'';
};
externalInterface = mkOption {
@@ -509,6 +578,17 @@ in
assertion = net.externalInterface != null;
message = "services.hermenix.network.externalInterface must be set.";
}
{
assertion =
!net.bridged || (net.lanAddress != "" && net.hostLanAddress != "" && net.lanGateway != "");
message = ''
services.hermenix.network.bridged = true requires a fully static
LAN setup (DHCP is no longer supported in bridged mode). Set
network.lanAddress (the guest's fixed LAN address),
network.hostLanAddress (this host's own LAN address, which moves
onto the bridge) and network.lanGateway (your router's address).
'';
}
{
assertion = cfg.backup.enable -> (cfg.backup.repository != "");
message = "services.hermenix.backup.repository must be set when backups are enabled.";
@@ -762,32 +842,120 @@ in
systemd.network.networks."10-${net.bridge}" = {
matchConfig.Name = net.bridge;
# hostAddress stays on the bridge in both modes: it is the guest's
# service net (host cache, hostAccess). In bridged mode the LAN DHCP
# lease is added on top of it.
address = [ "${net.hostAddress}/${toString net.prefixLength}" ];
# service net (host cache, hostAccess). In bridged mode the host's
# static LAN address is added on top of it - the bridge only ever has
# static addresses, never a DHCP lease.
address = [
"${net.hostAddress}/${toString net.prefixLength}"
]
++ lib.optional net.bridged "${net.hostLanAddress}/${toString net.lanPrefixLength}";
networkConfig = {
ConfigureWithoutCarrier = true;
IPv4Forwarding = true;
}
// lib.optionalAttrs net.bridged { DHCP = "ipv4"; };
// lib.optionalAttrs net.bridged {
# Static LAN config for the host: the bridge no longer takes a DHCP
# lease (bridged mode is static-only), so its gateway and DNS come
# from the module options instead.
Gateway = net.lanGateway;
DNS = if net.lanDns == [ ] then [ net.lanGateway ] else net.lanDns;
};
};
# The host's DNS, now that the bridge cannot learn it from a DHCP lease.
# mkDefault so the operator's own nameservers win if they set any.
networking.nameservers = lib.mkIf net.bridged (
lib.mkDefault (if net.lanDns == [ ] then [ net.lanGateway ] else net.lanDns)
);
systemd.network.networks."11-${net.tapId}" = {
matchConfig.Name = net.tapId;
networkConfig.Bridge = net.bridge;
};
# Bridged mode: the physical uplink becomes a bridge port so the LAN
# shares an L2 domain with the guest and the guest's DHCP is answered
# by the LAN itself. The port must not carry its own address config -
# the bridge owns the LAN address now. Note the bridge takes a fresh
# DHCP lease, and because its MAC can differ from the uplink's, the
# host's LAN IP may change after the first switch to bridged mode.
# shares an L2 domain with the guest. The port must not carry its own
# address config - the bridge owns the LAN address now (static, via
# hostLanAddress; there is no DHCP on the bridge).
systemd.network.networks."12-${net.externalInterface}" = lib.mkIf net.bridged {
matchConfig.Name = net.externalInterface;
networkConfig.Bridge = net.bridge;
};
# The bridge is created with no MAC of its own, so Linux makes it adopt
# the lowest-numbered port's MAC - and the tap is always the first port.
# That is how the host once ended up presenting the VM's MAC on the LAN
# (a duplicate address, since the guest uses the same MAC). Clone the
# uplink's MAC onto the bridge so the host keeps its LAN identity; the
# guest keeps its own tap MAC (net.mac).
systemd.services.hermes-bridge-mac = lib.mkIf net.bridged {
description = "Clone the uplink MAC onto the hermenix bridge";
after = [
"systemd-networkd.service"
"sys-subsystem-net-devices-${net.bridge}.device"
"sys-subsystem-net-devices-${net.externalInterface}.device"
];
wants = [ "systemd-networkd.service" ];
before = [ "network-online.target" ];
wantedBy = [ "multi-user.target" ];
serviceConfig = {
Type = "oneshot";
RemainAfterExit = true;
};
unitConfig.ConditionPathExists = "/sys/class/net/${net.externalInterface}";
script = ''
set -euo pipefail
# networkd creates the bridge netdev asynchronously; give it a moment.
for _ in 1 2 3 4 5 6 7 8 9 10; do
[ -e "/sys/class/net/${net.bridge}" ] && break
sleep 0.5
done
[ -e "/sys/class/net/${net.bridge}" ] || exit 1
mac="$(${pkgs.coreutils}/bin/cat /sys/class/net/${net.externalInterface}/address)"
${pkgs.iproute2}/bin/ip link set dev ${net.bridge} down
${pkgs.iproute2}/bin/ip link set dev ${net.bridge} address "$mac"
${pkgs.iproute2}/bin/ip link set dev ${net.bridge} up
# Re-apply the bridge's static address config under the new MAC.
${pkgs.systemd}/bin/networkctl reconfigure ${net.bridge} || true
'';
};
# The guest is handed its fixed LAN address (lanAddress) by a dedicated
# DHCP server bound to the bridge, keyed to the guest's MAC. This is the
# guest's ONLY DHCP: its broadcast is blocked from leaving the bridge
# (see the hermenix-bridge table), so the LAN's own DHCP server can
# never race the reservation. DNS is disabled (port=0) - the guest runs
# static QUAD9 resolvers, and this host gets its DNS from lanDns.
systemd.services.hermes-lan-dhcp = lib.mkIf net.bridged {
description = "Static-lease DHCP for the bridged hermenix guest";
after = [
"systemd-networkd.service"
"sys-subsystem-net-devices-${net.bridge}.device"
];
wants = [ "systemd-networkd.service" ];
wantedBy = [ "multi-user.target" ];
serviceConfig = {
Type = "simple";
Restart = "on-failure";
RestartSec = 5;
};
script = ''
for _ in 1 2 3 4 5 6 7 8 9 10; do
[ -e "/sys/class/net/${net.bridge}" ] && break
sleep 0.5
done
exec ${pkgs.dnsmasq}/bin/dnsmasq --keep-in-foreground \
--conf-file=/dev/null \
--interface=${net.bridge} \
--bind-dynamic \
--port=0 \
--dhcp-authoritative \
--dhcp-range=${net.lanAddress},${net.lanAddress},${netmaskFromPrefix net.lanPrefixLength},12h \
--dhcp-host=${net.mac},${net.lanAddress} \
--dhcp-option=option:router,${net.lanGateway}
'';
};
# ip_forward: use the same sysctl keys networking.nat used (mkOverride 99
# so they win over any lower-priority defaults elsewhere in the config).
boot.kernel.sysctl."net.ipv4.conf.all.forwarding" = lib.mkOverride 99 true;
@@ -856,6 +1024,13 @@ in
# Tag anything entering from the guest. ip-family input rules
# (host cache, hostAccess) match this mark.
iifname "${net.tapId}" meta mark set ${toString bridgeMark}
# The guest's address is static - served by hermes-lan-dhcp on
# this bridge - so keep its DHCP traffic off the LAN and keep the
# LAN's DHCP answers out of the guest. Only the host-side server
# may talk DHCP to it.
iifname "${net.tapId}" oifname "${net.externalInterface}" ether type ip ip protocol udp udp sport 68 udp dport 67 drop
iifname "${net.externalInterface}" oifname "${net.tapId}" ether type ip ip protocol udp udp sport 67 udp dport 68 drop
}
chain forward {
type filter hook forward priority filter; policy accept;
@@ -903,12 +1078,12 @@ in
# in hostAccess.
#
# NAT mode: the guest always arrives from its fixed service-net address,
# so match address + bridge. Bridged mode: the guest's LAN address comes
# from DHCP and is not known here, so the bridge table above tags guest
# traffic with a netfilter mark as it enters the tap - the rules match
# that mark instead. The tap is exclusive to the guest, so the mark is
# as specific as an address match: LAN devices can never inherit these
# holes.
# so match address + bridge. Bridged mode: the guest presents either the
# service-net address or its LAN address (served by the bridge's DHCP),
# so the bridge table above tags guest traffic with a netfilter mark as
# it enters the tap - the rules match that mark instead. The tap is
# exclusive to the guest, so the mark is as specific as an address
# match: LAN devices can never inherit these holes.
networking.firewall.extraInputRules =
if net.bridged then
optionalString cfg.hostCache.enable ''