Excellent (!) main reference https://www.cyrius.com/debian/kirkwood/qnap/

Special case ts-221 (and probably all devices with 1GB RAM): kernel of debian stretch 4.9 (also stretch-backports 4.17) seems to fail with memory above 768M on qnap arm
(discussion: https://groups.google.com/forum/#!topic/linux.debian.ports.arm/vSaO642z8aY); dmesg shows
BUG: Bad rss-counter state mm

  • use jessie installer in expert mode and install stretch (offered by jessie installer as testing release)
  • before reboot
    • either switch to older kernel as described below
    • or use only 768MB of 1024MB ram to avoid this bug
      mount /dev and /proc (maybe /sys) inside installation directory and chroot into installation directory

      • copy /usr/share/doc/u-boot-tools/examples/qnap_ts119-219.config
        to /etc/fw_env.config (assuming package u-boot-tools has been installed)
      • then run fw_printenv bootargs which returns something like
        bootargs=console=ttyS0,115200 root=/dev/ram initrd=0xa00000,0x900000 ramdisk=34816
      • now use fw_setenv to add linux kernel boot parameter mem=768M by adding mem=768M to output of fw_printenv
        fw_setenv bootargs “console=ttyS0,115200 root=/dev/ram initrd=0xa00000,0x900000 ramdisk=34816 mem=768M”
        (takes some time to write to flash)
      • check with fw_printenv that bootargs still contains the original arguments (plus mem=768M)
      • reboot (check with free -h and cat /proc/cmdline; dmesg: Memory: … 0K highmem)
      • maybe, this has to be repeated after every linux kernel update (verify withc fw_printenv bootargs if mem=768M ist still there)


In case flash-kernel returns Failed to obtain MAC address, run either
ubootcfg -b 0 -f /dev/mtdblock4 -o – | grep “^ethaddr=” | sed “s/^ethaddr=//”
or fw_printenv ethaddr
which returns the mac address stored in flash; then run
iface_set_mac eth0 YOUR_QNAP_MAC_FROM_FLASH

Recovery: run this iso from qnap wiki page inside a vm or install minimal debian with isc-dhcp-server and tftpd-hpa.

To make sure that an existing harddisk gets properly reconfigured use installer option (removal of raid partitions)
guided – entire disk

  • one partion with btrfs and option noatime
  • in case of error see below

Workaround (ok for devices without fan): If status led remains blinking red-green create /etc/rc.local, make it executable
qcontrol –direct statusled greenon
exit 0

Solution (fixes led, buzzer and fan): # qcontrol needs stretch backports: apt-get -t stretch-backports install qcontrol, so add to /etc/apt/sources.list

deb http://ftp.ch.debian.org/debian/ stretch-backports main

and /lib/systemd/system/qcontrold.services is broken: replaces lines

ConditionPathExists=/dev/input/by-path/platform-gpio_keys-event (kernel 4.9) or platform-gpio-keys-event (kernel 3.16)
and afterwards run
dpkg –configure qcontrol

In case one disk is used for the system and a second disk is used for data: mount the second disk in /etc/fstab with option noauto (else the system will not start if the data disk has been removed)

Install smartmontools and check disk with smartctl -a /dev/sdXN

Special case ts-221: does not run with kernel 4.9, so run debian stretch with kernel 3.6 -or use bootarg mem=768M as described above
(latest discussion: https://groups.google.com/forum/#!topic/linux.debian.ports.arm/vSaO642z8aY)

  • first install debian jessie (as described on cyrius.com for stretch but replace stretch by jessie in download links)
    • copy /boot/*, /lib/modules/*, /usr/lib/linux-image-* into a tar archive and save it on an external storage device
  • second, flash again the jesssie installer, but now run it in expert mode and install debian stretch
    • before rebooting the second last step “finish install or so” open console 2 (keys <ctrl> + <a>, then key <2>)
      • copy the saved contents of first installation (tar archive) into running installation
      • edit /usr/share/flash-kernel/functions: change force=”no” to force=”yes”
      • run update-initramfs -u -k 3.16..0-6-kirkwood (and probably you get a message to add “-t” as additional argument)
        later if kernel/initramfs get renewed, it is required to run afterwards: update-initramfs -u -k $(uname -r)

the installer does not cope well with already used disks (guided, use whole disk should work); if not, start installer in expert mode and add fdisk as installer component
(in case of running debian stretch wipefs -a removes all kind of signatures; but do double check that you will not wipe the wrong partition!)

  • open shell 2 and run cat /proc/partitions
  • use fdisk to create a new partition table (dos format) and create one big primary partion
  • create a filesystem on this partition with mkfs.ext2
  • reboot!!! And then run installer again in standard mode

Some qnap models may take more than 15 minutes until kernel and initrd are written to flash. – First reboot after installation might by succesful, even if power led keeps blinking red-green and buzzer remains silent. Led and buzzer need installation of qcontrol from backports and patched qcontrold.service file as described above.

Enable quota: btrfs quota enable /backup; btrfs quota enable /backup2
Display disk usage: btrfs sub list /backup; btrfs qgroup show /backup
unused because of to much memory usage when deleting snapshots

mkfs.btrfs shows after creation of filesystem whether incompatibilities with current kernel exist; use -O ^prop1,^prop2 if properties prop1,prop2 ar not compatible; (use wipefs to remove the newly created filesystem and recreate it using -O ^…)

Convert btrfs single partition filesystem to btrfs raid1 during debian install

  • use installer to create a btrfs root partition (noatime option) on a single partition
  • use installer to create on second disk a partition of same size without mountpoint
  • let installer write new partitions to disk
  • open second ssh connection and choose shell
    • btrfs filesystem show
    • df -h
    • btrfs device add -f /dev/PARTITION_ON_SECOND_DISK /target
    • btrfs balance start -dconvert=raid1 -mconvert=raid1 /target
    • btrfs filesystem show

Recover from failure of one drive of root filesystem on btrfs raid1

  • difficulty: if / gets remounted ro because of filesystem errors reboot into installer is required
  • prepare for rescue with installer
    • mkdir /var/backups/flash-installer
    • cd /tmp
    • wget http://ftp.debian.org/debian/dists/stretch/main/installer-armel/current/images/kirkwood/network-console/qnap/ts-21x/initrd
      wget http://ftp.debian.org/debian/dists/stretch/main/installer-armel/current/images/kirkwood/network-console/qnap/ts-21x/kernel-6282
    • dmesg |grep SoC
      ID=0x… displays wether kernel 6282 or 6281 is used
      cp initrd /var/backups/flash-installer/mtd2
      cp kernel-6282 /var/backups/flash-installer/mtd1 (or use kernel 6281)
    • to boot into installer run:
      cat /var/backups/flash-installer/mtd1 >/dev/mtdblock1
      cat /var/backups/flash-installer/mtd2 >/dev/mtdblock2
    • to restore installed system when running installer run:
      mount YOUR_PARTITION /mnt
      cat /mnt/var/backups/flash-kernel/mtd1 >/dev/mtdblock1
      cat /mnt/var/backups/flash-kernel/mtd2 >/dev/mtdblock2
  • recovery steps (if raid1 consists of /dev/sda3 and /dev/sdb3)
    • btrfs fi show
      displays whether both raid1 drives are accessible
    • echo 1 >/dev/block/sda/device/delete
      forces /dev/sda offline (e.g. in case of too many smart errors)
    • if btrfs fi show  displays that one drive is missing, e.g. sda3, do not run other btrfs commands to avoid errors which cause transition to ro filesystem, but do immediately run
      mount -o remount,degraded /dev/sdb3 /
    • attach replacement drive and check its device name with cat /proc/partitions (od dmesg), e.g sdc3
    • remove any existing btrfs data on replacement drive partition, e.g. on sdc3 by formatting it with ext4
      mkfs.ext4 -F /dev/sdc3
    • btrfs dev add -f /dev/sdc3 /
    • btrfs fi show
      • if sdc3 is shown twice, remove sdc3 with lower id from btrfs raid1
        btrfs dev del YOUR_DEVID /
      • if it is shown, that one drive is missing run
        btrfs del missing /
    • btrfs fi show
      this should know display two drives/partitions attached
    • to check for other error btrfs scrub might be run (time consuming)
    • reboot needed to remove option degraded from /proc/mounts

Switch hard disk with root filesystem

  • debian stretch on qnap sets kernel command line ROOT=”/dev/….” inside initramfs which is stored in flash. So using another hard disk requires to reflash initramfs
    • update-initramfs -u creates a new initramfs (at /boot/initrd.img-KERNEL_VERSION)
      and runs flash-kernel KERNEL_VERSION which creates /var/backups/flash-kernel/mtd2 (and mtd1) and flashes it
    • update-initramfs (/usr/share/initramfs-tools/hooks/flash_kernel_set_root) reads /etc/fstab to get the device with the root filesystem
    • use blkid YOUR_DEVICE_NAME to display the uuid of a block device
    • So to set a new root device, temporarily edit /etc/fstab (on the old root partition) to point to the new root filesystem device, run update-initramfs -u; then restore the old settings in/etc/fstab on old partition;
      verify that the new partition is correctly set in /etc/fstab on the new root partition,
    • additional step for recovery by tftp (based on instructions here)
      • backup flash partitions /dev/mtdblockN (N=0 … 5) to files mtdN
      • download installer kernel and initrd (reference)
        to determine kernel version (6281 or 6282)
      • pad kernel
        dd if=kernel-628X of=kernel.pad ibs=2097152 conv=sync (with X=1 or 2)
      • create tftp img file
        cat mtd0 mtd4 mtd5 kernel.pad initrd mtd3 > F_TS-219_di
        and copy this recovery image file to another computer or storage device
    • finally reboot
    • if reboot fails, load qnap recovery live cd iso here
      • run live cd in e.g. virtualbox (use a network adapter not connected to existing lan)
      • copy recovery image file to /tftpboot/ on live cd
        • add a second network interface connected to local lan to allow upload by ssh
        • sudo su
        • ifconfig eth1 YOUR_LAN_IP
        • set a password for user ubuntu
          passwd ubuntu
        • upload img file with scp to /home/ubuntu
        • ifconfig eth1 down (because dhcp server of live cd)
        • cp img file to /tftpboot/ and replace existing img file for your qnap device
      • power off qnap and power on with reset button pressed (until double beep):
        this should reflash qnap flash partitions with debian installer


Example btrfs send, btrfs receive (btrfs volumes mounted at /backup and at /backup2;
transfer readonly subvolume rootf_ro from volume mounted at /backup to other volume mounted at /backup2)

  • btrfs sub snapshot -r /backup/rootfs /backup/rootfs_ro

  • btrfs send /backup/rootfs_ro |btrfs receive /backup2

Resize/shrink btrfs partition with root filesystem (e.g. openmediavault needs separate data partition);
assume that btrfs partition is mounted at /backup using /dev/sda2

  • btrfs filesystem resize 32G /backup
  • fdisk /dev/sda
    • p
    • d 2
    • n 2 default start +40G
      do not delete btrfs signature
    • p
    • w
    • q
  • partprobe
  • btrfs filesystem resize max /backup
  • btrfs filesystem show
  • cat /etc/fstab

Add openmediavault (version 4.x arrakis for debian stretch): instructions

  • echo “deb http://packages.openmediavault.org/public arrakis main” > /etc/apt/sources.list.d/openmediavault.list
  • apt-get install openmediavault-keyring
  • apt-get update
  • apt-get install openmediavault
  • omv-initsystem

Create raid0 btrfs volume and use subvolumes as shared folders:

  • mkfs.btrfs -L datafs -d raid0 /dev/sda4 /dev/sdb4
  • then use webinterface filesystems to mount this volume
    (gets mounted at /srv/dev-disk-by-label-datafs; cat /etc/fstab)
  • btrfs subvol create /srv/dev-disk-by-label-datafs/YourShare
  • then use webinterface to define shared folder YourShare
    • use shared folder / ACL if write access fails
  • (in case of macos sierra don’t) share this folder by nfs
    • currently, 2017-11-02, apply changes fails
      (tries to mount second partition included in btrfs raid0)
    • reboot from console
    • log into webinterface and apply change again: should work
    • nfs://your_ip/export/YourShare/
      (with default settings needs option insecure)
    • currently, 2017-11-02, nfs with macos sierra is awfully slow but samba sharing (activate wins server) works
      • nfs seems to have locking issues because ejecting share from macos finder fails (unless finder is forced to restart)

minidlna media player

  • apt-get install minidlna
  • btrfs subvol create /srv/dev-disk-by-label-datafs/Musik
  • omv webinterface: add shared folder Musik on device with datafs
    which creates /sharedfolders/Musik
  • edit /etc/minidlna.conf (compare with this reference)
    • inotify=no
    • friendly_name=YOUR_MEDIA_SERVER
    • media_dir=A,/sharedfolders/Musik
  • chown -R minidlna:minidlna /sharedfolders/Musik
  • create media file index from scratch
    • systemctl stop minidlna
    • rm /var/cache/minidlna/*
    • systemctl start minidlna
  • if new mediafiles have been added
    • chown -R minidlna:minidlna
    • systemctl restart minidlna
  • if minidlna does not get discovered by plugplayer (ios), then manually add server:
  • to display status of minidlna use a webbrowser:


  • download deb from here
  • upload this file from omv webinterface section plugins
  • install plugin openmediavault-omvextrasorg
  • settings / system / OMV-Extras: activate wanted repository
  • check (again) for available plugins (or apt-get update)

Leave a Reply