---
name: qnap-dev
description: Use when a task or question concerns a QNAP NAS (QTS or QuTS hero), with or without Bucket & Code Server IDE, such as writing, building, packaging or debugging software, shell scripts, services, cron jobs or kernel modules for it; cross-compiling on your own Linux computer and packaging with QDK's qbuild; storage, paths, USB disks and backups; QPKG packages, App Center and package repositories; code signing and certificates; ports and networking; or a Bucket & Code Server IDE project (bvs env, bvs qbuild, App Builder, the kernel workshop). Also use when a command is "not found" on the NAS, a script works on your computer or in the editor's terminal but not from cron or init.d, or a binary fails with "GLIBC_2.xx not found".
---

# QNAP NAS guidelines

## Overview

A QNAP NAS runs Linux, but not a Debian-like Linux. Its root file system is a RAM disk rebuilt from the firmware at
every boot. Most classic commands are BusyBox 1.24.1 applets with fewer flags. There is no systemd and no package
manager, and settings live in `/etc/config` behind `getcfg` and `setcfg`. Check every command and path against what
the NAS has.

The NAS has no compiler, so you build somewhere else and ship the result. This skill covers two ways of working:

- On your own Linux computer, you build with QNAP's QDK, a cross toolchain or Go, copy the package to a shared
  folder on the NAS, and install it there with `qpkg_cli` in an SSH login.
- In Bucket & Code Server IDE (QPKG `bucketvs`), you build on the NAS itself, inside Debian or Ubuntu
  **environments** (chroots managed by `bvs env`), package with `bvs qbuild` and publish with `bvs repo publish`.

The facts about the NAS hold for both. Where the commands differ, the quick reference and the references give both.

## Where your code runs decides what it may call

| | Your own Linux computer | The editor's terminal, CI job on the NAS runner, the package's scheduled jobs | The NAS itself: init.d, a QPKG service script, `/etc/config/crontab`, an SSH login |
|---|---|---|---|
| Commands first on `PATH` | your distribution's: GNU coreutils, bash and what you install | the package's own tools in `/usr/bin/bucketvs/bin`: GNU coreutils (`timeout`, `nohup`, `printf`, `realpath`, `nproc`), bash, `pgrep`, `pkill`, `jq`, `make`, git, rsync, curl | BusyBox 1.24.1 applets and QNAP's own programs |
| `TMPDIR`, `HOME` | your own | `<data>/tmp`, `<data>/home/<account>` on a data volume | `/tmp` (a 64 MB tmpfs on QTS, 128 MB on QuTS hero 6.0), `/root` on the RAM disk |
| Compilers and packages | your distribution's package manager (`apt-get` on Debian or Ubuntu): compilers, cross toolchains, QDK | inside an environment: Debian or Ubuntu with `apt-get`, compilers and anything you install | nothing: the NAS has no compiler and no package manager |

A script that passes on your computer or in the editor's terminal can still fail on the NAS. Before you ship a script
that the NAS runs, run it on the NAS with only the firmware's folders on `PATH`, in an SSH login (copy it to a shared
folder first) or in the editor's terminal:

```sh
env -i PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin /bin/sh ./myscript.sh
```

## Can and cannot

| You can | You cannot, or should not |
|---|---|
| Ship static binaries, or dynamic ones that need only the NAS's glibc (Go with `CGO_ENABLED=0`; static dependencies with a dynamic glibc; App Builder's `static` or `bundle` link mode) | Install anything with `apt`, `dpkg`, `pip` or `npm` onto the NAS itself. Only your own computer or an environment has `apt-get` |
| Run a service from a QPKG's service script (`start`, `stop`, `restart`) that does `cd /` first: QTS starts it in a temporary folder it deletes | Write systemd units or call `systemctl` or `journalctl`: there is no systemd |
| Keep data on a data volume: the package's `Install_Path`, a shared folder, `getcfg SHARE_DEF defVolMP -f /etc/config/def_share.info` | Write outside your package on `/`, `/usr` or `/etc`: the RAM disk forgets it at the next boot. Or put large files in `/tmp`: a full `/tmp` takes the NAS down |
| Schedule with `/etc/config/crontab` followed by `crontab /etc/config/crontab`, or on Bucket & Code Server IDE's Jobs page | Use `crontab -e`: those edits are lost at reboot |
| Keep settings with `setcfg <QPKG_NAME> <Key> <Value> -f /etc/config/qpkg.conf` | Hard-code `/share/CACHEDEV1_DATA` or `/share/ZFS…_DATA`: resolve the volume |
| Build kernel modules for the running kernel in Bucket & Code Server IDE's kernel workshop and load them after its check | `insmod` a module built against another kernel, or one the check refused |
| Build QPKGs with QDK's `qbuild` on a Linux computer or with `bvs qbuild`, and publish code-signed ones to a repository App Center reads | Run the QDK Debian package's `qbuild` on QTS itself (there it looks for an App Center QDK), or tell anyone to allow unsigned apps in App Center |
| Use the forms that work on the NAS: a program's own time limit (`curl -m 30 --connect-timeout 10`), else a background job plus `kill`; `sh -c 'trap "" HUP; cmd &'` instead of `nohup`; `mkdir` as a lock; `getopts`, `netstat`, `busybox printf` | Rely on `timeout`, `nohup`, `flock`, `pgrep`, `pkill`, `getopt`, `ss`, `lsblk`, a bare `printf` or `realpath`, or GNU-only flags (`grep -P`, `find -printf`, `sort -h`) there |
| Build a dynamic program that needs no `GLIBC_` version newer than the target NAS's glibc: read the target's glibc first, then check the binary | Ship a program that needs a `GLIBC_` version the target lacks, or copy a newer `libc.so.6` next to it. Where the target's glibc is unknown or old, link static |
| Write to a USB disk through its share, after checking that its folder under `/share/external` is mounted | Write to a USB path without that check, or `mkdir -p` it: with the disk unplugged the files land in RAM |
| Ship your own copy of every tool the firmware lacks | Depend on Python, Perl, git, Docker or Entware being on the NAS: each exists only while some other QPKG is installed |
| Tell QuTS hero by `zpool`/`zfs` or `/share/ZFS*_DATA`, and the firmware generation by `uname -r` | Branch on `Version` in `/etc/config/uLinux.conf`: QuTS hero 6.x and QTS 6.0 report `5.2.10` there for compatibility |

The admin SSH login is already uid 0: `su` does not exist, and QTS 6.1's `sudo` has nothing to raise. Never probe
an unknown QNAP binary with `--help`: some take the first argument as data (`gen_hostname --help` renames the NAS).

## Quick reference

Building and publishing differ between the two ways:

| Task | On your own Linux computer | In Bucket & Code Server IDE |
|---|---|---|
| Build a program for the NAS | the cross toolchain for its processor (`aarch64-linux-gnu-gcc` for ARM, the computer's own `gcc` for x86_64), or Go with `CGO_ENABLED=0` | `bvs env run ubuntu2404-builder -- make` in the default builder (Ubuntu 24.04, glibc 2.39); `bvs env shell ubuntu2404-builder` for a shell inside |
| A runtime or cross toolchain | your distribution's packages (`gcc-aarch64-linux-gnu`, `g++-aarch64-linux-gnu`) | `eval "$(bvs use go-1.27-$(uname -m))"` in this shell |
| Will this binary run on the NAS? | `readelf -d` and `objdump -T` against the NAS's glibc ([building.md](references/building.md)) | `bvs ldd ./mytool` (exit 3 when a finding stops it); it reads the NAS it runs on |
| Install QDK, once | `apt-get install ./qdk_2.5.0_amd64.deb` after checking its sha256 ([qpkg.md](references/qpkg.md)) | `bvs tc install qdk-2.5.0-$(uname -m)` |
| Build a QPKG from `qpkg.cfg` in this folder | `qbuild`, then check the package's size | `bvs qbuild` |
| Put the package on the NAS for a test | `scp build/<file>.qpkg <account>@<NAS>:/share/<folder>/`, or SMB | it is there already, in `<data>/projects/<name>/build/` |
| Publish a signed QPKG | the package and a `repo.xml` on a web server ([app-center-and-repos.md](references/app-center-and-repos.md)) | `bvs repo publish build/<file>.qpkg` |

In an SSH login `bvs` is on `PATH` while Bucket & Code Server IDE runs: its start links `/usr/bin/bvs`, and its stop
takes the link away. The program itself is `/usr/bin/bucketvs/bin/bvs`.

On the NAS, the commands are the same either way:

| Task | Command |
|---|---|
| Install a QPKG for a test | `qpkg_cli -m /share/<folder>/<file>.qpkg --keep` (without `--keep` it deletes the file) |
| The default data volume | `/sbin/getcfg SHARE_DEF defVolMP -f /etc/config/def_share.info` |
| Your package's folder | `/sbin/getcfg <QPKG_NAME> Install_Path -f /etc/config/qpkg.conf` |
| A line in the NAS's System Logs | `/sbin/log_tool -t 0 -a "message"` (`-t 1` warning, `-t 2` error) |
| Is a daemon running? | `pidof <name>`, or its PID file; not `/etc/init.d/<x> status` |

`bvs ldd` answers for the NAS it runs on. From your own computer, or for another NAS, list the glibc versions the
NAS has, on that NAS:

```sh
strings /lib/libc.so.6 | grep '^GLIBC_2\.'   # a program runs there only if it needs no other GLIBC_ version
```

## Details, loaded when needed

Read the reference the task names; each one is short and cites its sources.

| Task | Reference |
|---|---|
| a script or a command for the NAS: BusyBox, services, settings (`getcfg`, `setcfg`), cron, System Logs | [references/nas-shell.md](references/nas-shell.md) |
| a command an Ubuntu answer would use, and its substitute; anything else never to suggest | [references/never-recommend.md](references/never-recommend.md) |
| where data lives, what survives a reboot, the volume and a package's folder, USB disks, storage commands | [references/storage-and-paths.md](references/storage-and-paths.md) |
| building on your own computer (cross toolchains, Go, checking a binary) or in environments, glibc and "`GLIBC_2.xx` not found", static programs, the App Builder, CI | [references/building.md](references/building.md) |
| writing App Builder recipes in a project (recipes/), the lint, static and aarch64 builds | [references/recipes.md](references/recipes.md) |
| a QPKG's files, `qpkg.cfg`, the service script, QDK's `qbuild` on your computer or `bvs qbuild`, installing for a test | [references/qpkg.md](references/qpkg.md) |
| code signing: a bought or a QNAP-issued certificate, the three cases (certificate files, a key on a USB token or HSM, none) | [references/signing.md](references/signing.md) |
| App Center, a repository's `repo.xml`, a repository of your own on a web server, the package repository, `bvs repo publish` | [references/app-center-and-repos.md](references/app-center-and-repos.md) |
| ports: checking one, the firmware's, where to bind, the package's own | [references/networking-ports.md](references/networking-ports.md) |
| backups: what to copy, backup scripts, snapshots, the package's Backups page | [references/backups.md](references/backups.md) |
| a kernel module for the NAS's own kernel | [references/kernel-modules.md](references/kernel-modules.md) |

## Code signing in three lines

The certificate is bought from a certificate authority or issued by QNAP; App Center checks any other than QNAP's
against the certificate authorities the NAS trusts ([signing.md](references/signing.md)).

1. **A certificate as files** (`certificate`, `private_key`, `ca_certs` next to `qpkg.cfg`): supported. QDK's
   `qbuild` signs the package, on your own computer or through `bvs qbuild`, and needs `openssl` and `hexdump`
   (`bsdextrautils`) where it runs.
2. **A key on a USB token or an HSM** (`certificate_hsm` next to `qpkg.cfg`, the key reached through PKCS#11):
   QDK's `qbuild` signs through openssl's engine `pkcs11` with `HSM_SLOT` and `HSM_KEY_ID` or `HSM_KEY_LABEL`.
   Tried with a software token, not with a USB token. From 1.0.0-73 (x86_64) `bvs qbuild` and a project's Build sign
   with a token plugged into the NAS (`bvs token list` shows it); 1.0.0-72 and earlier refuse it.
3. **No certificate:** the package is unsigned. Other NAS units install it only if their owners allow unsigned
   apps, which you never recommend.

## Red flags: stop and check the reference

- You are about to write `apt install`, `systemctl`, `sudo`, `timeout`, `nohup`, `pgrep`, `flock` or `python3`
  in something the NAS runs, or a background-and-kill loop around a program that has its own timeout option.
- A path starts with `/tmp/` and the file could be large, or has to survive a reboot.
- A script writes to a USB disk and never checks that the disk is mounted.
- A path names `CACHEDEV1_DATA` or `ZFS` literally.
- "`GLIBC_2.xx` not found", and you have not read the target NAS's glibc; or a static glibc program looks up users
  or hosts.
- A module was built in a tree that was not prepared from the running kernel's profile.
- An answer suggests turning on "allow apps without a valid digital signature", or `repo.accept_unsigned`, or
  copying a certificate authority's root into the NAS's `/etc/ssl/certs` so that a package installs.
- An answer sets `HSM_SLOT` to a slot's position from `pkcs11-tool --list-slots` instead of its id, or retries a
  token's PIN in a loop.
- A storage command (RAID, pool, volume, file system) goes out without the warning that it can be irreversible.
- An answer gives `bvs` commands to someone who works without Bucket & Code Server IDE.
- `qbuild` wrote a package much smaller than its files, or `QPKG_VER` is longer than ten characters
  ([qpkg.md](references/qpkg.md)).

## Sources

The facts about the NAS come from QNAP Club Poland's knowledge base (forum.qnap.net.pl), measured on QTS 6.1 and
QuTS hero 6.0 units: the bundle's index [llms/llms.txt](https://forum.qnap.net.pl/llms/llms.txt) (the forum's own
index of how-to threads is [llms.txt](https://forum.qnap.net.pl/llms.txt)),
[guidelines.md](https://forum.qnap.net.pl/llms/guidelines.md),
[ai-guidelines-hero60.md](https://forum.qnap.net.pl/llms/ai-guidelines-hero60.md),
[ai-exclusions-qts61.md](https://forum.qnap.net.pl/llms/ai-exclusions-qts61.md),
[absent-commands.json](https://forum.qnap.net.pl/llms/absent-commands.json) (the machine-readable list),
[linux-gap.md](https://forum.qnap.net.pl/llms/linux-gap.md), and the per-command help text
[help-qts61.txt](https://forum.qnap.net.pl/llms/help-qts61.txt), with
[storage-layout.md](https://forum.qnap.net.pl/llms/storage-layout.md) and
[services-qts61.md](https://forum.qnap.net.pl/llms/services-qts61.md). Cite them when you relay a NAS fact, and
keep the conditions of the forum's [AI policy](https://forum.qnap.net.pl/ai-policy.md): cite the source, and warn
before any storage command. The facts about building, the package repository and backups in Bucket & Code Server
IDE come from its user guide (`bvs guide`); the facts about signing from QDK 2.5.0's `qbuild` and from measurements
on QTS 6.1 (App Center's check of a non-QNAP chain) and with a software token. The facts about
building on your own computer were measured while building QPKGs with QDK 2.5.0 on Ubuntu 24.04 for QTS 6.1 and
QuTS hero 6.1 units.

## Licence

QNAP guidelines skill by QNAP Club Poland / qnaputilities.com, CC BY 4.0. The skill's files are under the Creative
Commons Attribution 4.0 International License: share and adapt them with that line and a link to the licence
([LICENSE](LICENSE)).
