A bridged server's network card sits on vmbr2, a bridge whose port is the node's uplink. Its frames leave with its own MAC (an OVHcloud virtual MAC, or a MAC the provider gave the address) instead of being routed by the node. Use it when the provider requires a per-address MAC, or when a guest needs to be a plain machine on the provider's network.
Routed servers keep working on the same node. Read Routed IPv4 and IPv6 first: for most OVHcloud and Hetzner additional IPs, routed is simpler and needs no change to the node's uplink.
When to use bridged#
| Situation | Block type |
|---|---|
| OVHcloud additional IPs, and you want each to leave with its own virtual MAC | Bridged, MACs OVHcloud virtual MAC |
| Hetzner single IPs ordered with a separate MAC | Bridged, MACs Entered per address |
| OVHcloud or Hetzner additional IPs, the node's MAC is fine | Routed (Routed) |
| A subnet on a Hetzner vSwitch or an OVHcloud vRack VLAN | VLAN |
Requirements#
- The node's network is managed by netplan rendering to systemd-networkd (Debian 12 and 13 cloud images, Ubuntu). ifupdown and NetworkManager are refused: build the bridge by hand there.
- The uplink has a global IPv4 address. A spare interface used instead must be physical, have a link and no address.
- Anti-spoofing is on in the node's agent configuration (
anti_spoofing: truein/etc/vmstack/agent.yaml, the default). A bridged block is refused on a node without it. - An agent with bridged networking (its
/v1/inforeportsbridge). - For OVHcloud virtual MACs: an OVHcloud account in System › Settings, panel Reverse DNS, whose API rights include
GET /dedicated/server/*andPOST/DELETE /dedicated/server/*/virtualMac*, and the node's OVHcloud service name. - Access to the provider's console (KVM, IPMI) or rescue system while you set up the bridge.
Set up the uplink bridge#
The agent builds vmbr2 only when you ask on the node page. Never at install, upgrade or start, and never because a bridged block was added.
- Go to Infrastructure › Nodes, open the node, and find the Bridged networking panel on its Overview tab.
- For OVHcloud: enter the OVHcloud service name (the server's name in the OVHcloud control panel, such as
ns1234567.ip-203-0-113.eu) and click Save service name. - Click Set up the bridge.
- Choose the Interface: the uplink (with its addresses shown), or a spare interface with no address.
- Type the node's name to confirm, and click Set up the bridge.
The button is refused while the node has tasks queued or running, or is not online. On an OVHcloud node the panel first asks OVHcloud whether the server takes virtual MACs, and sets up the bridge once it says yes.
What happens during the switch#
- The agent checks the node (netplan, systemd-networkd, exactly one netplan definition of the interface, not in a bond or bridge) and computes the new netplan files: the uplink's addresses, DHCP, routes, DNS and IPv6 move to
vmbr2, which carries the uplink's MAC. It validates them withnetplan generatebefore anything changes. When cloud-init is installed, it adds/etc/cloud/cloud.cfg.d/99-vmstack-network.cfgso cloud-init does not write its own network file back. - It writes its state and arms a rollback timer in systemd (
vmstack-bridge-rollback, 300 seconds), outside the agent's process. - It writes the files and runs
netplan apply. The node is without network for a few seconds: SSH sessions and the servers' traffic pause. - Within 60 seconds it checks that
vmbr2is up with the interface as its port, holds the node's addresses and default route, and that the gateway answers. If not, it rolls back at once. - The panel reads the result through the new bridge and confirms it. Only then does the agent stop the timer and mark the bridge active.
If the panel cannot confirm, the timer puts the old files back within 5 minutes. A reboot before the confirmation rolls back at the agent's start. The panel shows the state (pending with its deadline, active, rolled_back with the reason) and the audit log records each step. While a change is pending the agent does not update itself.
If the node stays unreachable after the deadline, reach it through the provider's console and run the rollback by hand:
/usr/local/bin/vmstack-agent bridge rollback -config /etc/vmstack/agent.yaml
Undo the bridge#
Undo the bridge writes the netplan files back as they were before the setup, with the same timer and confirmation. It is refused while any server is bridged, and refused when the netplan files were edited by hand since the setup (undo it by hand then).
Add a bridged block#
- Go to Infrastructure › IP pools › Add IP block, choose IPv4 and the node.
- Choose Bridged: each address has its own MAC (OVHcloud virtual MAC, Hetzner separate MAC).
- Enter the Network (
203.0.113.8/29, or a single address) and check the Gateway: it is the node's own gateway, outside the block. At OVHcloud the gateway of a bridged additional IP is the dedicated server's own gateway. - Choose the MACs (below), and click Add IPv4 block.
Every address of the block is usable. Servers use each address as a /32 with that gateway on-link. Bridged blocks are not probed by the address check: the guest itself answers ARP on the uplink. A bridged block's reverse DNS account defaults to the account of its MACs.
OVHcloud virtual MACs made by the panel#
Choose OVHcloud virtual MAC, account …. The panel creates a virtual MAC through the OVHcloud API when a server gets an address of the block, and deletes it when the address is released. Fixed MACs are refused on such a block.
MACs entered per address#
Choose Entered per address for Hetzner's separate MACs, or OVHcloud MACs you made by hand. Enter each address's MAC with Set fixed MAC on the block's page, or import them as CSV (IP pools). An address without a MAC is never given to a server.
Which servers are bridged#
Addresses are given lowest first, whatever the type. The server's main address decides its kind:
- A server whose main address is bridged is a bridged server. Its additional addresses come only from bridged blocks of the same OVHcloud account (OVHcloud puts them on the server's one virtual MAC).
- A bridged main address with a hand-entered MAC allows no additional address: each such address has its own MAC, and a server has one card.
- A routed or on-link server never gets a bridged additional address.
- Bridged addresses are given only while the node's bridge is active; otherwise they are skipped and the node page says why.
A bridged server:
- has no IPv6 and cannot be behind NAT in this version (the create form and the API refuse it);
- cannot be moved to another node ("A bridged server keeps its provider MAC on its node: release its addresses first");
- has no per-server firewall in this version (
firewall_unavailable). The node's network rules protect it instead (below).
OVHcloud virtual MACs: create, wait, release#
All OVHcloud calls run as queue jobs on the panel's dns queue, never in a page request. Check the worker runs (systemctl status vmstack-worker@dns-1).
Create. A server whose main address is in an OVHcloud bridged block waits in Building: "Waiting for OVHcloud to make the virtual MAC of 203.0.113.9 (usually one to five minutes)". The job reuses a virtual MAC the address is already on, or asks OVHcloud for a new one and follows OVHcloud's task every 15 seconds. It then adds the server's additional addresses to the same MAC and sends the create to the node.
If OVHcloud refuses (an address not routed to this server, a quota) or does not finish within 30 minutes, the server goes to Error with "OVHcloud could not make the virtual MAC of …:
Add an address to a running bridged server: the node is told at once, and the job puts the address on the server's MAC. If OVHcloud does not, the address stays with the server, marked on the server and block pages with Try again.
Release (server deleted, address removed, failed create): the address is taken off its MAC (OVHcloud deletes the MAC with its last address) before anybody gets it again. A removal that fails waits on the block's page with Try again and Forget. Use Forget only after removing the virtual MAC in the OVHcloud control panel yourself.
An OVHcloud account in use for MACs cannot be removed from the settings.
Routed and bridged blocks on one node#
A node with an active uplink bridge can keep routed, on-link and NAT blocks. After the switch the agent applies the routed network (proxy ARP, IPv6 proxy entries, NAT, DHCP) to the new uplink vmbr2; routed servers stay on vmbr0 as before.
So on an OVHcloud or Hetzner node you can add one additional block as Routed (servers leave with the node's MAC) and another as Bridged (servers leave with their own MAC). One block is one type: the same addresses cannot be in two blocks. To change a block's type, free its addresses, delete it and add it again.
DHCP on bridged servers#
The provider does not answer DHCP for bridged addresses, so the agent runs its own small DHCPv4 responder for bridged and VLAN servers. A server installed from an ISO (Windows, a Linux netinst) gets its network by DHCP without typing it in.
- It answers only a server's own MAC on its own tap, and writes the answer into that tap only: it never reaches the uplink or another server. Unknown MACs get nothing.
- The server's DHCP requests are dropped at the bridge, so the provider's network never sees them.
- The lease is the seed's: the main address, netmask
255.255.255.255(OVHcloud), router = the gateway, classless static routes 121 and 249 (<gateway>/32on-link, then the default route via it) for Windows and other clients, the DNS servers, the host name, and an infinite lease. - Additional addresses are not given by DHCP: configure them inside the server. The server's Network tab lists them.
- Servers installed from images keep their static configuration; one that asks DHCP gets the same values.
The node page's DHCP server line shows · N bridged while the responder answers N servers, and its problem in red when it cannot open its socket.
Note: the responder needs an agent with the bridged DHCP responder; with an older agent, ISO installs on bridged addresses get no DHCP answer and must be configured by hand (the address as
/32, the gateway, the DNS servers). Windows taking the on-link gateway from the classless routes has not yet been confirmed on a live node; if it does not, set the address statically.
Protections on the bridge#
Bridged traffic is not routed, so the node's network rules apply on the bridge itself (bridge vmstack_rules), to the servers' taps only, never to the uplink port:
- DHCP and DHCPv6 server answers from servers are always dropped, and so are router advertisements;
- VLAN-tagged frames from and to servers are dropped;
- ARP and neighbour discovery flood limits, the metadata address block, outbound SMTP and ping follow the node's settings (Node settings).
libvirt's clean-traffic binds each card to its MAC and addresses.
Not supported#
- Automatic uplink changes: the bridge is never made at install, upgrade or start.
- ifupdown and NetworkManager nodes.
- IPv6 and NAT for bridged servers; moving bridged servers; the per-server firewall on bridged servers.
- Hetzner's API: Hetzner MACs are entered by hand.