Installing openSUSE Leap on QNAP TVS-h1688X NAS

Implementing a Computing Solution

KVM OPENSuSe QNAP Virtualization

Introduction

a Personal Take

For some many years, I've been running my Linux computing services on secondhand IBM equipment and as I considered scaling down, I decided to move to QNAP NAS devices with virtualization. For the first couple of years, this was a complete success. However upgrades to QNAP software introduced a range of issues and major instability that I could no longer run what I was running either in terms of the number of virtual servers or reliability. Backs would fail, snapshots would kill the server IP stack, virtual servers would just shut off. It became untenable, so I moved back to a single 1U server, leaving a fully populated NAS unused.

After seeing the NAS sitting off in the MCR, I wondered could I install Linux on the box and give it new life as a virtualization server? The answer was a resounding YES! Here are my notes for anyone else who is thinking of doing a similar thing. I work with OpenSUSE Linux, however, I imagine there would be many flavors of Linux that could be used. I did try to install XEN virtualisation, however, it came down to BIOS limitations that made this impossible. I implemented KVM on Linux RAID/LVM partitions and it works like a treat.

Project Guide Overview

 

This guide walks through the process of replacing the QNAP QTS/QuTS operating system on a TVS-h1688X NAS with openSUSE Leap. It includes safety measures, recovery testing, live OS verification, installation, and post-setup tasks such as configuring RAID and the watchdog timer. It should be noted, that ChatGPT was used in the rendering of this project and the associated notes.

Step 1: Obtain QNAP Recovery Material

Purpose: Ensure you can recover the NAS in case installation fails or OS is bricked.

  1. Understand Recovery Image Limitations:

    • .img files such as TS-X88_20250321-h5.2.4.3079.img are not bootable by themselves; they are firmware payloads.

    • Bootable recovery ISO images are typically not publicly available for the TVS-h1688X.

  2. Option A – Request QNAP Recovery ISO:

    • Go to https://service.qnap.com/

    • Request a UEFI-compatible Firmware Recovery ISO for TVS-h1688X.

    • QNAP support can provide a bootable image with embedded tools for flashing the DOM.

  3. Option B – Use Qfinder Pro for Network Recovery:

    • Download and install Qfinder Pro

    • Power off NAS and remove all drives

    • Power on the NAS – it should enter recovery mode and be visible to Qfinder Pro

    • Qfinder will prompt you to upload the .img firmware file and will flash it over LAN

  4. Option C – Manual Flash Using Live Linux:

    • Boot the NAS using a working Linux Live USB (e.g., openSUSE Live)

    • Use lsblk to identify the QNAP DOM module (e.g., /dev/sdX)

    • Use dd to write the firmware image directly:

      sudo dd if=TS-X88_20250321-h5.2.4.3079.img of=/dev/sdX bs=512k

    • Be extremely cautious: writing to the wrong device can destroy data

  5. Backup Configuration (Optional but Recommended):

    • Login to QTS GUI > Control Panel > Backup/Restore > Backup Settings

    • Export config .bin file and store it securely (e.g., USB drive or cloud)

Step 2: Perform a Mock Recovery

Purpose: Test that recovery works and verify reinstallation path is valid.

  1. Disconnect All Drives

  2. Insert recovery USB (or use Qfinder Pro without drives)

  3. Connect monitor and keyboard to NAS

  4. Power on the NAS and enter advanced BIOS setup:

    • Press Del or Esc during boot

    • Then press Ctrl + Alt + F1 to enter advanced UEFI options

  5. Set recovery USB as the primary boot device (or network recovery if using Qfinder)

  6. Follow on-screen instructions or Qfinder prompts to flash firmware

  7. Confirm successful boot into QTS interface

  8. Power off and remove recovery media (reconnect drives later if needed)

Step 3: Prepare Hardware for Installation

Required Components:

  • Monitor (HDMI input)

  • USB keyboard

  • USB mouse (optional)

  • USB drive with openSUSE Leap ISO (e.g., LEAP 15.6)

  • Spare SSD or HDD for Linux OS (avoid existing RAID disks)

Step 4: Test openSUSE Leap Live Environment

Purpose: Validate hardware compatibility.

  1. Create Live USB with openSUSE Leap (using Etcher/Rufus)

  2. Insert USB into NAS

  3. Power on and boot from USB:

    • Press F11 or F12 for the boot menu

    • If options don’t appear, enter BIOS using Del, then use Ctrl + Alt + F1 for full boot option access

Checklist of Components to Verify:

  • Monitor and Keyboard Input Works

  • Ethernet Interfaces Recognized (ip a)

    • 4 x 2.5GbE NICs

    • 2 x 10GbE NICs

  • Drives Visible (lsblk)

  • Temperature Sensors Detected (sensors)

  • Fan RPM Values Detected (sensors or /sys/class/hwmon/...)

  • RAID Controller Detected (if present) via lspci or lsmod

Exit Live session safely after validation.

Step 5: Install openSUSE Leap to NAS

  1. Boot from openSUSE Leap installer USB

  2. Select target installation disk (e.g., spare SSD or NVMe)

  3. Partitioning: Use default Btrfs or configure LVM if preferred

  4. Bootloader: Ensure GRUB is installed to target drive

  5. Install minimal system (or graphical if preferred)

  6. Set new hostname, root password, and user account

  7. On reboot, enter BIOS and set new Linux drive as first boot device

  8. Boot into openSUSE Leap

Step 6: Configure Watchdog and Monitoring Tools (and Webmin)

  1. Install Watchdog (Software or systemd-based):

    sudo zypper install watchdog

    If not available, enable systemd watchdog support by editing /etc/systemd/system.conf:

    RuntimeWatchdogSec=10
ShutdownWatchdogSec=10min

    Then reload:

    sudo systemctl daemon-reexec

  2. Enable Watchdog Service:

    sudo systemctl enable watchdog.service
sudo systemctl start watchdog.service

  3. Verify Hardware Watchdog Support (Optional):

    ls /dev/watchdog*
dmesg | grep -i watchdog

  4. Install Sensors and Fan Tools:

    Add Base:System repo if required:

    sudo zypper refresh
sudo zypper install sensors

  5. Detect and Test Sensors:

    sudo sensors-detect
sensors

Step 7: Install Webmin for Web-Based Monitoring

Webmin provides a powerful browser-based interface to manage system settings, including disk health, RAID, services, and system resources.

wget https://www.webmin.com/download/rpm/webmin-current.rpm
sudo zypper install perl-Net-SSLeay
sudo rpm -Uvh webmin-current.rpm

  • Open port 10000 in the firewall:

sudo firewall-cmd --permanent --add-port=10000/tcp
sudo firewall-cmd --reload

  • Access Webmin at: https://<NAS-IP>:10000

Use your system root credentials to log in.

Step 8: Set Up Linux Software RAID (if applicable)

If no hardware RAID controller is detected, proceed with mdadm:

  1. Install mdadm:

sudo zypper install mdadm

  1. Assemble/Build Array:

sudo mdadm --create --verbose /dev/md0 --level=5 --raid-devices=4 /dev/sd[abcd]

  1. Create Filesystem:

sudo mkfs.ext4 /dev/md0

  1. Mount RAID:

sudo mkdir /mnt/data
sudo mount /dev/md0 /mnt/data

  1. Make Persistent: Add to /etc/fstab

To check RAID status:

cat /proc/mdstat

If Hardware RAID is Present:

  1. Detect controller:

lspci | grep RAID

  1. Install vendor tools (e.g., storcli, megacli, or arcconf) depending on controller

  2. Follow vendor-specific CLI or BIOS setup to configure RAID volume

End Notes:

  • Keep the QNAP DOM untouched (unless you intend to wipe it). You can always restore using QNAP’s recovery method.

  • Only use fresh drives or SSD for the Linux OS to avoid QNAP RAID conflict

  • After testing, consider configuring Samba/NFS for file sharing or ZFS for advanced filesystem features.

You now have a fully independent Linux NAS system running on QNAP hardware.

QNAP LCD Display Control on openSUSE Leap

Overview

This section describes how to control the LCD panel on a QNAP TVS-h1688X NAS from openSUSE Leap, displaying custom messages dynamically using a configuration file.

Requirements

  • QNAP TVS-h1688X NAS with openSUSE Leap installed

  • LCDproc built from source (as covered earlier)

Step-by-Step Instructions

1. Install required tools

sudo zypper install git gcc make autoconf automake libtool libusb-1_0-devel ncurses-devel

2. Build and install lcdproc

git clone https://github.com/lcdproc/lcdproc.git
cd lcdproc
chmod +x autogen.sh
./autogen.sh
./configure
make -j$(nproc)
sudo make install

3. Configure LCDd

Edit /usr/local/etc/LCDd.conf and set:

Driver=hd44780
DriverPath=/usr/local/lib/lcdproc/

[hd44780]
ConnectionType=usb
Device=/dev/hidraw0  # Adjust if needed

4. Create message configuration file

Create /etc/QNAPLCD_message.cnf:

System Ready
NAS Up

5. Create update script /usr/local/bin/lcd_message.sh

#!/bin/bash
MESSAGE_FILE=/etc/QNAPLCD_message.cnf
LINE1=$(head -n 1 "$MESSAGE_FILE")
LINE2=$(tail -n 1 "$MESSAGE_FILE")
lcdexec "$LINE1
$LINE2"

Make it executable:

sudo chmod +x /usr/local/bin/lcd_message.sh

6. Run LCDd

sudo /usr/local/sbin/LCDd

7. Update message

To change the message:

echo -e "System Alert       
Temp High          " | sudo tee /etc/QNAPLCD_message.cnf

The display updates automatically within 1–2 seconds.


Instruction Manual - NAS SSD Cache

SSD Cache Setup for KVM on openSUSE Leap (QNAP TVS-h1688X)

Niyshah Pty Ltd - ABN 31 616 613 604, Eric Belcher

Read Next