When you connect an external USB network (Ethernet) dongle to a node running XCP-ng, you might encounter an issue where the device appears as a "side-NUMBER-eth0" interface. This interface, however, is not connected and cannot be used for any management interfaces within XCP-ng. You may still be able to manually configure it and to assign IP addresses but it will be still refused to be used for the management interface. To resolve this, you need to rename the device appropriately. Unfortunately, simply renaming the interface won’t work; you need to define a udev rule to ensure proper configuration. Here’s a detailed guide on how to correctly set up your USB network dongle on XCP-ng - keep in mind, that you mostly only want to use this kind of network for your dev labs and not for production usage!

First, you need to identify the external USB network dongle interface and its hardware (MAC) address, as well as the assigned uuid for the pif. This information can be obtained when running the following commands on the cli of the related node:

    ip addr show
    xe pif-list

Afterwards, a new udev rule file will be created. Adjust the following line by replacing it with your previously noted hardware address (not the pif uuid) of the interface. Therefore, create a new file in the /etc/udev/rules.d/ directory and name it 70-persistent-net.rules. Copy in the following content:

    SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="bc:00:11:22:33:44", ATTR{type}=="1", KERNEL=="eth*", NAME="eth0"

You may encounter issues by a previously loaded udev rule which you might want to deactivate. This rule renames the unrecognized devices. Therefore, just move the file 60-net.rules out of the drop-in directory.

Within the last step, we need to remove the known configuration for the pif. This can be done by removing the pif uuid (not the interface hardware address) from the system and rebooting afterwards:

    xe pif-forget=UUID
    reboot

By following these steps, you’ll be able to properly configure your external USB network dongle on XCP-ng, ensuring it is correctly recognized and usable for management interfaces. This process involves identifying the interface, creating a udev rule to rename it, and removing any old PIF references. After completing these steps, your USB network dongle should be fully functional and integrated into your XCP-ng environment.

Are you interested into XCP-ng? You can find out more about in my blog post right here.