Networks
Updated
Machines get a real presence on your network through a Linux bridge. Virtainer Free does not run its own DHCP server, NAT, or address management: your existing network keeps doing that job.
Only wired Ethernet interfaces are supported. Wi-Fi interfaces are excluded from setup and network configuration; connect an Ethernet adapter if none is available.
The two kinds of network
Section titled “The two kinds of network”- The management network is how you reach the host itself. There is exactly one, and it is the one that can lock you out.
- VM networks are what machines attach to. New machines use the host’s default VM network unless you pick another.
A bridged management network can also carry machines. A management interface that is not bridged cannot, and Virtainer Free refuses rather than quietly breaking your access.
The bridge the host migrates its own address onto is named vmbr0, and it is the
default VM network as well. You will see that name in host-side logs and in support
output.
Creating a network
Section titled “Creating a network”The Networks page builds networks from recipes that cover the common shapes:
| Recipe | What it gives you |
|---|---|
| Dedicated | A bridge on its own uplink |
| Isolated | A segment with no uplink, for machines that should only talk to each other |
| Bonded uplink | A bridge over bonded interfaces |
| VLAN segment | A tagged segment on an existing interface |
There is also a structured editor for the cases the recipes do not cover, and a topology view showing how interfaces stack up. The management branch is locked by default in that editor, and unlocking it is deliberate.
Changing or deleting a network
Section titled “Changing or deleting a network”Only two things about an existing network can be edited: its name, and the security policy defaults described in Per-machine policy. Reach and uplink are fixed at creation, and the console says so on the edit form. Changing the shape of a network means creating a new one and moving your machines onto it.
Deleting a network is refused while any machine is attached to it. The message names the network by its id and how many machines are attached. That count looks at every network interface on a machine, so a machine whose main interface is on another network still blocks the delete if it has a second interface on this one. Detach that interface, or delete the machine, before you delete the network.
Three more refusals do not depend on that count. The management network cannot be deleted at all. A network that carries the host’s default route cannot be deleted either, so move the host’s address elsewhere first. And a network that snapshots or detached pooled interfaces still depend on is refused until you acknowledge it in the delete confirmation: restoring those snapshots would fail once the network is gone, and a pooled interface on it could not be attached again.
Deleting is confirmed by typing the network’s name. The confirmation names the bridge that will be torn down and states that connected machines lose this network until they are reattached.
The confirmation window
Section titled “The confirmation window”This is what makes management network changes survivable when the configuration is wrong but the host is still talking: leave it alone and it undoes itself.
It is not a general rescue, and the distinction matters. The window cannot recover a change that removes the link itself. If you are editing the bridge that carries the host’s only reachable interface, arrange out-of-band access to the machine, or have someone on site who can power-cycle it, before you apply. Waiting out the five minutes is not a safe plan in that case.
If the change moves the host to a new address, the console reopens a confirmation page at the new address, and you will not have to sign in again to confirm it.
You do not have to wait for the five minutes to run out. The window has two exits: Keep this network finishes the change, and Discard (revert) puts the previous configuration back right away. Either one closes the window, and discarding is the faster route to a second attempt.
Only a change that touches the management network opens a window at all; everything else is applied directly. The host takes one network change at a time. While a window is open, another change that touches the management network is refused because another network change is still inside its confirm window, and editing the topology is refused because a management network change is awaiting keep or discard. Either refusal clears as soon as you resolve the pending change.
If the host restarts while a window is open, the previous configuration is still restored when the window expires or you discard, so a reboot does not leave you stranded on the unconfirmed one. While the window is open you can still keep the change.
The host’s actual state decides what counts as dangerous, not only the record: the branch that carries the host’s current default route is treated like the management network, so changing it opens a window and deleting it is refused. The network section of the diagnostics report flags a record that disagrees with the host.
A window also freezes the rest of the host: while one is open the host refuses to reboot or shut down, refuses to complete first-run setup, and holds back the automatic reboot after an OS update.
Some changes need explicit acknowledgement even when they are correct: taking over an interface that carries the default route, planning a configuration with no default route at all, or demoting the current management interface.
Per-machine policy
Section titled “Per-machine policy”Two controls apply to a machine’s own network attachment:
- Anti-spoof restricts a machine to its own address and MAC, so it cannot claim to be something else. Extra source addresses can be allowed explicitly.
- Port isolation stops a machine talking directly to its neighbours on the same bridge.
Both can be set on the network as a default and overridden per machine. Each one resolves through three layers, most specific first: the machine’s own override, the default on the network it is attached to, and the host default. The host default is a Host defaults card on the Networks page, below the network list, and the per-machine and per-network selectors name it in place, as in Follow host default (currently On). The console shows the value that is actually in effect and where it came from, so there is no ambiguous inherited setting to guess at.
Both can be changed while the machine runs. A change to a network’s policy is pushed to the machines on it immediately, except where a machine has its own override, which continues to win.
Network interfaces
Section titled “Network interfaces”A machine’s network interface is its own resource, not a field on the machine. The Interfaces page lists every interface on the host: the ones attached to a machine and the ones sitting in the pool, with their MAC address, network, address, and the machine each is attached to.
- Create interface puts a new interface in the pool. Choose its network and settings; the MAC address is generated if you leave it empty.
- Attach hands a pooled interface to a classic VM. It is checked like any new interface: the per-machine interface limit, a single default gateway, and a network that still exists.
- Detach takes an interface off a machine and keeps it in the pool, with its MAC address, network, and policy overrides intact, so it can be attached again. Detaching the machine’s first interface drops the cloud-init address settings it carried, and attaching it again makes it the last interface. A machine can be left with no interface at all; its serial console still works.
- Delete removes an interface for good. An attached interface is detached first.
Classic VMs take interfaces while running (hot-plug) or stopped. A machine that is starting or paused waits, and an AppVM’s network is part of its workload, so its interfaces are not edited here. The row buttons are disabled with the reason. Tick several rows to delete them in one pass; each is run in turn and the ones that could not be deleted are listed with the reason.
NIC offloads
Section titled “NIC offloads”NIC offloads enables checksum and packet-segmentation offloads for all network interfaces on a classic VM, giving much higher throughput.
Some Linux guest kernels have a network driver bug that shows up only with offloads on:
ping, DHCP and outbound connections work, but the guest drops nearly all incoming TCP, so
SSH and any other service on the VM are unreachable. Inside the guest, nstat -az TcpInCsumErrors keeps climbing. Turning offloads off for that VM restores the connection
straight away.
The bug is in the upstream Linux kernel from 6.10 (and in stable kernels it was backported to) until it was fixed. A kernel is affected when it is older than the fixed version of its branch:
| Kernel branch | First fixed version |
|---|---|
| Upstream 6.6 (6.6.36 and later) | 6.6.117 |
| Upstream 6.12 | 6.12.59 (Debian 13: 6.12.63) |
| Upstream 6.17 | 6.17.9 (Fedora 43: 6.17.9-300.fc43) |
| Upstream 6.9 (6.9.7 and later), 6.10, 6.11, 6.13 to 6.16 | Never fixed on those branches; move to a fixed branch |
RHEL, Rocky and AlmaLinux 10 (6.12.0-*.el10) |
Release 267 (6.12.0-267.el10) |
| Ubuntu 6.8 (6.8.0-44 and later) | 6.8.0-103 |
| Ubuntu 6.17 | 6.17.0-14 |
| Ubuntu 6.11 and 6.14 | Never fixed on those branches |
“Upstream” means a kernel numbered with the upstream release, as Fedora, Debian, Arch,
Alpine, ELRepo and Amazon Linux kernels are. The Ubuntu rows apply to the generic,
lowlatency and virtual kernels. Ubuntu’s cloud kernels have their own numbers; the 6.11
and 6.14 cloud kernels (every flavour, including kvm) were never fixed either. On the other branches Virtainer uses the
versions below; a flavour and branch marked “Not covered” is treated as unaffected.
| Ubuntu kernel flavour | 6.8 bug introduced | 6.8 first fixed | 6.17 first fixed |
|---|---|---|---|
aws |
6.8.0-1015 | 6.8.0-1048 | 6.17.0-1007 |
azure |
6.8.0-1014 | 6.8.0-1048 | 6.17.0-1008 |
gcp |
6.8.0-1014 | 6.8.0-1049 | 6.17.0-1007 |
oracle |
6.8.0-1012 | 6.8.0-1045 | 6.17.0-1007 |
ibm |
6.8.0-1012 | 6.8.0-1046 | Not covered |
nvidia |
6.8.0-1013 | 6.8.0-1048 | Not covered |
realtime |
Not covered | Not covered | 6.17.0-1006 |
Kernels from 6.18 on, and older branches such as 6.1, are not affected.
A kernel whose version does not show its upstream patch level is treated as unaffected and
keeps offloads on. That covers vendor kernels that keep an X.Y.0 base and backport fixes
themselves, such as SUSE Linux Enterprise and openSUSE Leap 16 (6.12.0-160000), Oracle
UEK and openEuler, as well as Ubuntu 6.8 and 6.17 kernels of other flavours (for example
kvm) and any version
Virtainer cannot read. SUSE 16 kernels do have the bug today: if such a VM answers ping but
not SSH, turn its offloads off.
Offloads default to On for creation and reinstall, except when every kernel installed in the image is affected. Virtainer reads the installed kernels from the image’s RPM package database, so this applies to images such as Fedora, RHEL, Rocky and AlmaLinux 10.0 to 10.2, openSUSE Tumbleweed, ELRepo and Amazon Linux 2023 with an affected kernel. For those images the default is Off, with the reason and the fixed kernel version shown in the create form’s Network row and recorded in the creation or reinstall operation. This is based on the image’s kernels, not its distribution name alone; for example, the Fedora 43 Cloud image ships an affected kernel and defaults to Off. Debian and Ubuntu images, and images whose kernels are treated as unaffected, default to On.
Your explicit choice takes priority. Reinstalling without an explicit choice recalculates the default from the new image. VMs created before Free 1.2 keep offloads Off. To change the setting, stop the VM and use NIC offloads under Hardware → Network interfaces. The change takes effect at the next boot. AppVMs keep offloads off and have no switch.
If the guest agent reports an affected running kernel while offloads are on, including on Debian and Ubuntu guests, Hardware shows a warning and Diagnosis reports a failure that names the kernel version with the fix. Either fix works:
- Turn offloads off for that VM: stop it, switch off NIC offloads under Hardware → Network interfaces, and boot it.
- Update the guest kernel to the fixed version or later (on Fedora 43,
sudo dnf upgrade kernel), reboot the guest, and keep offloads on, or turn them on if they were off.
When offloads are off and the reported kernel is unaffected, Diagnosis offers an optional throughput improvement.
What Free does not do
Section titled “What Free does not do”Cross-host overlay networks, VXLAN creation, and internal NAT private networks are not part of Virtainer Free. Networking spanning more than one host belongs to Virtainer Pro. See Virtainer Pro.