Rebind SR-IOV Virtual Functions with netplan rebind

netplan rebind reattaches a physical function's virtual functions to their driver, and it can knock traffic off a workload while it does it. Allow 10 to 15 minutes for a proper maintenance window; this is an operational change, not a harmless status check.

This guide follows the installed netplan-rebind(8) manual and Netplan 1.1.2 from the netplan.io package on Ubuntu 24.04, version 1.1.2-8ubuntu1~24.04.3 on the reference host. Other releases can differ, so check the local help before copying an option into a script.

1. Confirm the command and the maintenance boundary

Run these read-only checks as your normal account first. They confirm Netplan is installed and show the syntax without touching any network device:

$ dpkg-query -W -f='${Package} ${Version}\n' netplan.io
netplan.io 1.1.2-8ubuntu1~24.04.3
$ command -v netplan
/usr/sbin/netplan
$ netplan rebind --help
usage: /usr/sbin/netplan rebind [-h] [--debug] [--root-dir ROOT_DIR]
                                [netdevs ...]

The installed command also advertises --root-dir, while the manual documents -h, --help, --debug, and a space-separated interface list. This guide sticks to the documented interface list and --debug. Do not assume a flag from a newer binary exists on another host.

2. Identify the physical function

netplan rebind takes physical-function interface names, not VF names. Pull the host's own inventory rather than guessing:

$ ip -br link
lo               UNKNOWN        00:00:00:00:00:00
enp5s0f0         UP             52:54:00:12:34:56
enp5s0f1         DOWN           52:54:00:12:34:57

The output is host-specific; enp5s0f0 is only an example. Confirm the candidate against your platform's SR-IOV inventory and whatever workload uses it. To tell a PF from a VF, inspect the device without changing it:

$ ethtool -i enp5s0f0
driver: example-driver
version: host-specific

Not every driver exposes identical fields, and the output is not a Netplan contract. What you want is a consistent name and a known maintenance target. If the interface is a bond member, bridge port, or assigned to a guest, write that dependency down before continuing.

3. Check the Netplan configuration before rebinding

Netplan's SR-IOV model ties a VF to a PF through the link property, roughly like this:

network:
  version: 2
  ethernets:
    enp5s0f0:
      mtu: 1500
    vf0:
      link: enp5s0f0

That is an example of the relationship, not something to paste over your existing file. Keep the host's current addressing, routes, VLANs, renderer and other settings intact. A VF can use a Netplan ID that differs from the kernel interface name, so check the real files under /etc/netplan/ and the generated state before acting:

$ sudo netplan get all
network:
  ethernets:
    enp5s0f0:
      mtu: 1500
    vf0:
      link: enp5s0f0

netplan get all is read-only. If it fails, fix the configuration error first. netplan apply is not a substitute here; it is a separate operation with a wider blast radius and it is outside this guide.

4. Rebind one physical function

Warn anyone on the affected network path, stop or evacuate dependent workloads per your platform's procedure, then run the command with the PF name. It normally needs elevated privileges because it changes kernel device-driver attachment:

$ sudo netplan rebind enp5s0f0

Do not add a VF name here. The manual describes the positional argument as a space-separated list of physical-function names. For several independent PFs, list each one deliberately:

$ sudo netplan rebind enp5s0f0 enp5s0f1

Keep the list short while troubleshooting: an explicit one-PF run makes it easier to pin down what caused a failure and limits the blast radius. Add the documented debug switch if you need more detail:

$ sudo netplan --debug rebind enp5s0f0

5. Verify the result and recover if needed

Once the command returns, inspect links and the driver state. These checks are read-only:

$ ip -br link
$ ethtool -i enp5s0f0
$ ip link show

Confirm the expected PF and VFs are present, the driver is the intended one, and the dependent workload has its network path back. Use the workload's own health check too: the exact link state, VF names and driver output depend on the NIC, kernel, driver and deployment.

If a VF or workload does not come back, stop repeating the rebind blindly. Check kernel messages and whatever service or virtualisation manager owns the device:

$ sudo journalctl -k -b --no-pager | tail -n 100
$ sudo systemctl status your-dependent-service.service

Replace the service placeholder with a real unit name. Recovery: if rebinding caused an outage, restore the previous device assignment or service configuration, then restart only the affected consumer via its documented procedure. Keep the original Netplan files intact. Editing configuration and applying it is a separate, potentially disruptive change; do not improvise it mid-incident without an approved recovery plan.