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.20.1 | 4.2 | ARMv7 32-bit | Compiled for TS-x31x series | Download |
| 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/
This weekend I decided to finally try some more troubleshooting, so I booted up my QNAP with the ethernet disconnected, once it was on, I connected it and logged in to see that qbittorrent was disabled (which I thought I had done of course) which ruled it out as the cause.
Being not sure what to do, I looked at some settings and made one change. I had previously manually set the Realtek as the primary adapter and the built-in NIC as secondary. So I turned that off and set everything back to automatic, and then left the ethernet connected to the realtek and no ethernet in the built-in NIC.
Lasted for several days, but today, it is once again inaccessible. I'm not sure what else to do. I don't know whether the OS is locking up, or just losing networking only. I wonder if I can write a script that can check for connectivity, and when it is lost for a certain amount of time, have it initiate a reboot of the NAS automatically or restart network services to avoid me having to hard shut down the device while I try to figure out the problem. If a script like this fails to get things back online when this situation happens, it points more to a system issue bigger than just the networking stack.
And what worries me is that there are other symptoms that point in that direction. For example, the status leds on the front all go static, meaning they stop blinking entirely. And the lcd display stops displaying anything when i press the buttons. But on the other hand, it just did it twice in a row, but the lan lights still turned on when i plugged into the local NIC after the freeze, and the lights were orange, indicating a degraded state.
It's probably time for me to replace it. But I was hoping to use it for a while longer until I'm ready to make that investment. Anyone have other ideas for me to try? Maybe it's a coincidence this started at the same time I set up the USB adapter? or something I modified along the way has had unintended consequences?
edit: one more important detail. sometimes this issue happens immediately after the reboot. not just after several days. 50/50 chance of either scenario. Then i have to shut it off a 2nd time.
Edit #2: This seems to be getting worse. i don't why I can't replicate what has worked all the other times I rebooted, but now, within minutes of every hard reset, networking is failing again. This is making it nearly impossible to make it through the steps to implement this script I had chatgpt help me create. I'm going to keep trying.....