Automatically Connect Realtek RTL8156 USB 2.5G NICs to Proxmox Servers

When running Proxmox, I often faced a unique challenge in managing my virtualization infrastructure. My Proxmox cluster, consisting of 3 HP EliteDesk 800 G5 Mini, was equipped with only a single 1Gbps Ethernet interface, which became a performance bottleneck, especially for my demanding workloads and replication tasks. To overcome this limitation, I wanted to supplement my servers with 2.5Gbps USB network interface cards (NICs), such as the UGREEN USB 3.0 to 2.5Gbps Ethernet Adapter, to establish a mesh-connected cluster.

However, I encountered a common issue – these USB NICs would fail to reconnect automatically after server restarts or power cycles. This unpredictable behavior led to disruptions and the need for manual intervention, which was both time-consuming and frustrating.

To address these challenges, I developed a solution that enables the automatic connection of USB NICs to my Proxmox servers. By leveraging system tools and custom Udev rules, this approach ensures a seamless and reliable network setup, eliminating the hassle of unreliable USB NIC connections.

In this article, I will guide you through the step-by-step process of configuring this solution, empowering you to expand your Proxmox cluster's network capabilities and maintain a stable, highly available infrastructure, just as I have done.

inxi:

To begin the configuration process, we'll need to install the inxi tool, which will provide us with valuable information about the USB NICs connected to our Proxmox servers. Run the following command to install inxi:

apt install inxi

Get NIC-ID, Vendor-ID, Device-ID:
With inxi installed, we can now gather the necessary details about the USB NIC we want to automatically connect to our Proxmox cluster. Use the inxi -n and lsusb commands to obtain the NIC-ID, Vendor-ID, and Device-ID:

inxi -n
lsusb

These identifiers will be crucial in the upcoming steps, so make sure to take note of them.

Add required modules:

Next, we need to ensure that the necessary kernel modules are loaded for the USB NIC to function properly. Open the /etc/modules file with a text editor:

nano /etc/modules

And add the following lines:

r8152
cdc_mbim
cdc_wdm
cdc_ncm
cdc_ether
usbnet
mii

These modules will enable the USB NIC to be recognized and configured correctly by the system.

Udev:

Finally, we'll create a custom Udev rule to automatically bring up the network interface when the USB NIC is plugged into the Proxmox server. Create a new file in the /etc/udev/rules.d/ directory:

nano /etc/udev/rules.d/01-<NIC>.rules

Replace <NIC> with a descriptive name for your USB NIC, and add the following rule:

SUBSYSTEM=="net", ACTION=="add", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="8156", RUN+="/sbin/ifup <NIC>"

Make sure to replace the idVendor and idProduct values with the ones you obtained earlier using the lsusb command.

This Udev rule will automatically bring up the network interface when the USB NIC is plugged in, ensuring a seamless and reliable connection.

Install usb_modeswitch:

To handle the device ID changes that can occur when re-plugging the USB NICs, we'll need to install the usb-modeswitch and usb-modeswitch-data packages. Run the following command to install them:

apt-get install usb-modeswitch usb-modeswitch-data -y

Create re-plug script:

Next, we'll create a custom script that will unplug and re-plug the USB NICs to ensure they're properly recognized by the system. Open a new file in the /usr/local/bin/ directory:

nano /usr/local/bin/restart_nics.sh

And add the following script:

#!/bin/bash

# This script unplugs and re-plugs the USB NICs

# Wait for a moment to ensure that the system has fully started
sleep 10

# Unplug USB NICs
echo "Unplugging USB NICs..."
sudo usb_modeswitch -v 0bda -p 8151 -R
sudo usb_modeswitch -v 0bda -p 8156 -R
sudo usb_modeswitch -v 0bda -p 8151 -R
sudo usb_modeswitch -v 0bda -p 8156 -R

# Wait for a moment to ensure that the devices have been reset
sleep 5

# Re-plug USB NICs
echo "Re-plugging USB NICs..."
sudo usb_modeswitch -v 0bda -p 8151
sudo usb_modeswitch -v 0bda -p 8156
sudo usb_modeswitch -v 0bda -p 8151
sudo usb_modeswitch -v 0bda -p 8156

echo "Finished!"

Make the script executable:

chmod +x /usr/local/bin/restart_nics.sh

Create system service:

To ensure that the USB NICs are automatically re-plugged on system startup or reboot, we'll create a systemd service. Open a new file in the /etc/systemd/system/ directory:

nano /etc/systemd/system/restart_nics.service

And add the following service configuration:

[Unit]
Description=Restart USB NICs
After=network.target

[Service]
ExecStart=/bin/bash /usr/local/bin/restart_nics.sh

[Install]
WantedBy=default.target

Activate and start service:

Finally, enable and start the restart_nics.service to ensure it runs at system startup:

sudo systemctl daemon-reload
sudo systemctl enable restart_nics.service
sudo systemctl start restart_nics.service
sudo journalctl -u restart_nics.service

By following these steps, you've now set up a comprehensive solution to automatically connect and manage your USB NICs in your Proxmox cluster, ensuring a stable and reliable network infrastructure.