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/
Some ideas -
Could the 431P2 be short of memory? Are there many additional applications running in the 431P2? In r8152.c - if routine alloc_all_mem encounters some kind of memory error then goto err1 which issues free_all_mem around line 2586.
You might issue dmesg then scroll down to the modprobe r8152, and start looking for interesting messages. Don't use grep. There could be interesting messages without 'r8152'. Maybe post the messages from the modprobe r8152 to the error messages, hopefully there are other messages with this chunk which shed more light on the situation.
Good luck!