Note
This guide was last updated on 17th Feb 2025
Many QNAP NAS devices only come with 1Gbe network interfaces. These devices can easily benefit from a simple network upgrade by connecting the ubiquitious 2.5Gbe USB NICs from Realtek. Unfortunately, some of the older QNAP NAS systems do not support the newer r8156 based 2.5Gbe NICs or r8157 based 5Gbe NICs as they run an older 4.x linux kernel and the r8152 source files included with the older linux kernel are based off an older codebase that predates the 8156/8157 series.
With some elbow grease however, we can build support for the 2.5 & 5 Gbe adapters and easily upgrade functionality.
Whilst any Linux build environment may be possible, I have chosen the older Debian 8. We need to download and install the latest Debian 8 i386 instance from Debian: https://www.debian.org/releases/jessie/debian-installer/
Once our Linux VM is installed, we must also setup the environment for build. Login as "root" user and install the development packages using apt:
apt-get install build-essential libelf-dev bcOther libraries may be required depending on the kernel/module build options
In order to compile the kernel module for a respective QNAP system, we must identify the compiler on which the system was built. This can be done by querying the NAS itself using an SSH terminal:
cat /proc/versionThis will show an output like:
Linux version 4.2.8 (root@U16BuildServer176) (gcc version 4.8.2 20131014 (prerelease) (crosstool-NG linaro-1.13.1-4.8-2013.10 - Linaro GCC 2013.10) ) #2 SMP Thu Jun 29 05:42:26 CST 2023
In the case of the TS-431P arm based system, the kernel was built using linaro-1.13.1-4.8-2013.10, so we need the relevant cross compiler. QNAP have not included this compiler in their GPL Open Source repository so we must obtain it from linaro: https://releases.linaro.org/archive/13.10/components/toolchain/binaries/gcc-linaro-aarch64_be-linux-gnu-4.8-2013.10_linux.tar.bz2
Extract the contents to a directory such as the /opt folder.
QNAP provides other platform cross-compilers on their sourceforge repository: https://sourceforge.net/projects/qosgpl/files/QNAP%20NAS%20Tool%20Chains/
The NAS Kernel source is available on sourceforge: https://sourceforge.net/projects/qosgpl/files/QNAP%20NAS%20GPL%20Source/
In the example of the TS-431P, we will download and extract GPL_QTS-5.0.0-20211101_Kernel.tar.gz
To complete the build environment, we must copy the appropriate config file for kernel compilation.
In the case of the TS-431P:
cp ~/cp GPL_QTS/kernel_cfg/TS-X31X/linux-4.2-arm.config ~/GPL_QTS/src/linux-4.2/.configAlternatively, one could also extract this config from the running NAS by downloading and extracting the contents under /proc/config.gz (if available).
This file can then be copied to the respective linux src folder.
Example:
gunzip config.gz
cp config ~/GPL_QTS/src/linux-4.2/.configWith our build environment set up, we must then compile the linux kernel.
We can do so with a simple command (ensuring we reference our extracted folder locations appropriately:
make ARCH=arm CROSS_COMPILE=/opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_linux/bin/arm-linux-gnueabihf- -C ~/GPL_QTS/src/linux-4.2/ scripts prepare modules_prepareDownload optimized compiled driver:
| Release | Kernel | Architecture | Comments | Link |
|---|---|---|---|---|
| 2.19.2 | 4.2 | ARMv7 32-bit | Compiled for TS-x31x series | Download |
Other precompiled driver repositories:
Download and extract the USB Linux drivers from Realtek's website: https://www.realtek.com/en/component/zoo/category/network-interface-controllers-10-100-1000m-gigabit-ethernet-usb-3-0-software https://www.realtek.com/Download/List?cate_id=585
As of (updated) writing, the current version is 2.19.2
If compiling for the older 4.x Linux kernel, we must first modify the contents of the r8152.c source file and replace strscpy with strlcpy for driver versions 2.17.1 onwards. This is to allow compilation on older kernel instances as these versions do not support the strscpy function.
If we don't change this function, we will see an error like below:
make: Entering directory '/root/GPL_QTS/src/linux-4.2'
WARNING: Symbol version dump ./Module.symvers
is missing; modules will have no dependencies and modversions.
CC [M] /root/r8152-2.17.1/r8152.o
/root/r8152-2.17.1/r8152.c: In function ‘rtl8152_get_drvinfo’:
/root/r8152-2.17.1/r8152.c:18623:2: error: implicit declaration of function ‘strscpy’ [-Werror=implicit-function-declaration]
strscpy(info->driver, MODULENAME, sizeof(info->driver));
^
cc1: some warnings being treated as errors
scripts/Makefile.build:270: recipe for target '/root/r8152-2.17.1/r8152.o' failed
make[1]: *** [/root/r8152-2.17.1/r8152.o] Error 1
Makefile:1503: recipe for target '_module_/root/r8152-2.17.1' failed
make: *** [_module_/root/r8152-2.17.1] Error 2
make: Leaving directory '/root/GPL_QTS/src/linux-4.2'
We can quickly replace the functions in the file using sed:
sed -i -e 's/strscpy/strlcpy/g' r8152.cAlternatively, download forked source from GitHub which contains the necessary fixes and enhancements: https://github.com/RikshaDriver/realtek-r8152-linux
Now we can finally compile the Realtek module:
make ARCH=arm CROSS_COMPILE=/opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_linux/bin/arm-linux-gnueabihf- -C ~/GPL_QTS/src/linux-4.2 M=`pwd` modules EXTRA_CFLAGS='-O2'We should now have the succesfully compiled kernel module r8152.ko
In order to install the Realtek USB driver on our Linux system, we must overwite the existing r8152.ko module under /lib/modules/<kernel-version>/
For a quick an dirty test, upload the kernel module to a folder on the NAS, copy to the modules directory and run modprobe to remove and probe the kernel module. For example, the command for TS-431P (and related devices):
cp r8152.ko /lib/modules/4.2.8/
modprobe -r r8152
modprobe r8152The Realtek driver should immediately show up as a network interface:
dmesg | grep 8152
[16401.642702] usbcore: deregistering interface driver r8152
[16404.197265] usbcore: registered new interface driver r8152
[16404.851196] r8152 2-4:1.0 eth2: v2.17.1 (2023/06/13)
[16404.856178] r8152 2-4:1.0 eth2: This product is covered by one or more of the following patents:
Tip
If experiencing adapter stability issues, it is possible the NAS may not be providing sufficient power to the adapter. Consider using an externally powered USB 3 Hub or a USB 3 Y cable which is connected to an external USB power source.
For a more permanent installation, the same commands can be run at startup using the autorun.sh capability of the NAS.
We must first tick the "Run user defined process during startup" option to allow autorun.sh loading during bootup.
The autorun.sh file must be stored on the flash storage.
QNAP provides a few methods of mounting the flash storage: https://www.qnap.com/en/how-to/faq/article/running-your-own-application-at-startup
In our case, we will do as follows:
/etc/init.d/init_disk.sh mount_flash_configWe can now manually create or upload our autorun.sh file to /tmp/nasconfig_tmp/autorun.sh
Example autorun.sh:
#!/bin/sh
echo "############ autorun.sh script start ############" >> /dev/kmsg
cp /share/CACHEDEV1_DATA/r8152.ko /lib/modules/4.2.8/
cp /share/CACHEDEV1_DATA/50-usb-realtek-net.rules /lib/udev/rules.d/50-usb-realtek-net.rules
modprobe -r r8152
modprobe r8152
sleep 5
udevadm control --reload-rules && udevadm trigger
sleep 10
echo "############ autorun.sh script end ############" >> /dev/kmsgEnsure autorun.sh is executable:
chmod +x /tmp/nasconfig_tmp/autorun.shOnce completed, unmount the flash drive:
cd ~/
/etc/init.d/init_disk.sh umount_flash_configReboot and enjoy 2.5Gb/s or 5Gb/s speeds!
The Kernel module can also be packaged as a QPKG and run at startup as an application. This is similar to what is done with the Advanced Network Drivers application from QNAP.
Refer to the QDK guide for more details on creating a QPKG: https://cheng-yuan-hong.gitbook.io/qdk-quick-start-guide/
Thanks for this. This will help and prevent me from having to buy a new NAS for a while longer.
I just wanted to share two adapters I found that worked on my 431p NAS
Asus USB A to 2.5G eth adapter. This did not require a USB powered hub
ASUS 2.5G Ethernet USB Adapter (USB-C2500)
https://a.co/d/2y4zHyF
WAVLINK 5Gbps USB C to Ethernet Adapter, 5000Mbps USB-C to RJ45 Network Converter with 95W Charging Port, Aluminum Case RTL8157 Chipset. BIG heat sink and barely gets warn to the touch even when I tried with charging my MacBook Pro with the USB-C power pass through. I think I will be buying another one of these for my laptop.
https://a.co/d/3QrRNoj
WAVLINK Also make one without the power pass through for a few dollars less but I didn’t test that version.
For the WAVLINK to work at 2.5GB you will also need a USB-C to USB-A that is for USB 3.2 or it will just connect at 1GB
The one that works for me was:
“GRAUGEAR USB-C Adapter, 10Gbps Double Sided Data Transfer, 3A Fast Charging, USB C Female to USB A Male Adapter 3.2”
https://a.co/d/7XnAYoo
I currently have the WAVLINK running at 2.5G for the last 72 hours doing a lot of transfers and stress testing.
I will be getting my new router with SPF+ and 10G module to copper this week and then should be able to test the 5G speed.
I’m guessing the 5G will pull more power and the reason I bought the USB-C pass through version . My hope is that I can just provide more power to it using a USB-A to USB-C cable on the NAS with a different USB port. I have already tested and confirmed that putting power into the pass through while plugged into a USB-A does not direct any power to the NAS since it can’t do the handshake like USB-C expects. But if it uses this extra power for the Ethernet chip is unconfirmed, and I would not be able to test that for sure unless I tear this one down.
Side Notes:
While testing these adapters I did make them the default gateway on the NAS and unplugged the other 1GB Ethernet on the NAS.
I tested one other 2.5GB and 5GB adapter and they both ran hot and were not stable.
I will comment again once I test the 5GB speed and receive my new router.
I hope this helps,
Scott