How to modify network interface name pinning in Proxmox VE

    This article explains how to change the names assigned to physical network interfaces in Proxmox VE when the automatic order doesn't match the expected logical layout.

    The Problem

    Starting with Proxmox VE 8.2, the system uses network interface pinning to assign stable names (nic0, nic1, nic2...) to physical network interfaces based on their MAC address. This prevents names from changing after kernel, driver, or BIOS updates.

    However, in some cases the automatically assigned numbering doesn't match the logical order of PCI slots or the physical layout of network cards.

    How Name Pinning Works

    Proxmox uses the pve-network-interface-pinning tool to generate systemd .link files that map a MAC address to a stable interface name.

    Files generated by the tool are stored in:

    /usr/local/lib/systemd/network/

    Each file follows the pattern 50-pve-nicX.link (or 50-pmx-nicX.link in older installations) with the following format:

    [Match]
MACAddress=02:00:00:00:00:01
Type=ether

[Link]
Name=nic5
    • The [Match] section identifies the physical interface by its MAC address and type.
    • The [Link] section defines the name to be assigned to that interface at boot.

    Method 1: Using the Official Tool (Recommended)

    The safest way to rename an interface is using the official tool with the --target-name option:

    pve-network-interface-pinning generate --interface nic5 --target-name nic6

    This command:

    • Generates the corresponding .link file
    • Automatically updates /etc/network/interfaces
    • Updates the host firewall configuration
    • Updates SDN configuration if in use

    After running the command, verify the proposed changes:

    diff /etc/network/interfaces /etc/network/interfaces.new

    If the changes are correct, reboot the server to apply them:

    reboot

    Reverting Changes Before Reboot

    If you detect issues in the generated .new files, you can revert by removing the temporary files and created .link files:

    rm /etc/network/interfaces.new
rm /usr/local/lib/systemd/network/50-pve-nic*.link

    Method 2: Manual .link File Editing

    To swap names between two existing interfaces, you can manually edit the .link files.

    Step 1: Verify Existing Files

    ls /usr/local/lib/systemd/network/

    Step 2: Create Backups

    cp /usr/local/lib/systemd/network/50-pve-nic5.link{,.bak}
cp /usr/local/lib/systemd/network/50-pve-nic6.link{,.bak}

    Step 3: Swap the Names

    Modify the Name= value in each file:

    sed -i 's/Name=nic5/Name=nic6/' /usr/local/lib/systemd/network/50-pve-nic5.link
sed -i 's/Name=nic6/Name=nic5/' /usr/local/lib/systemd/network/50-pve-nic6.link

    Step 4: Update the initramfs

    The .link files are copied to the initramfs, so it needs to be updated:

    update-initramfs -u -k all

    Step 5: Reboot the Server

    reboot

    Important Notes

    • Bridges update automatically: If the interfaces are assigned to bridges (vmbr0, vmbr1, etc.) in /etc/network/interfaces, you don't need to modify that configuration. Bridges reference the interface name, so they will follow the swap automatically.
    • Recommended names: If assigning custom names, use names starting with en or eth so Proxmox recognizes the interface as a physical device in the GUI. Avoid names that could clash with systemd's scheme (like eno, enp, ens).
    • The prefix may vary: Depending on the Proxmox version, files may use the prefix 50-pve- or 50-pmx-. Verify with ls before editing.
    • Firewall and SDN: If using Proxmox firewall or SDN, verify that interface references are updated in /etc/pve/nodes/<nodename>/host.fw and /etc/pve/sdn/.

    Troubleshooting

    Changes don't apply after reboot

    1. Verify that you edited the files in the correct path.
    2. Confirm that you ran update-initramfs -u -k all.
    3. Check the logs: journalctl -b | grep systemd-network.

    Can't find the .link files

    If the /usr/local/lib/systemd/network/ directory is empty, name pinning is not configured. You can generate it with:

    pve-network-interface-pinning generate

    Conflict between .link files

    If files with different prefixes (50-pve- and 50-pmx-) exist for the same interface, delete the duplicates and keep only one.

    Published