# QPKG packages

A QPKG is how software is installed on a QNAP NAS: a self-extracting archive that QNAP's QDK builds with `qbuild`,
installed by App Center, started and stopped by QTS through the package's service script.

## The files

Bucket & Code Server IDE's New project "QPKG package" template makes this folder. On your own computer,
`qbuild --create-env <name>` makes QDK's own template: `qpkg.cfg`, `package_routines`, `shared/<name>.sh`, a folder
per processor (`x86_64`, `arm_64`, `arm-x41` and older ones), `icons/`, `config/` and `build_sign.csv`. Put your
program under `shared/bin/` yourself.

```text
qpkg.cfg                 name, version, service script, firmware floor
package_routines         QDK's install and remove hooks
shared/<name>.sh         the service script, copied into the install folder
shared/bin/<name>        your program (any file under shared/ is installed for every processor)
x86_64/, arm_64/         optional: files for one processor (arm-x41 for 32-bit ARM)
build/                   where qbuild writes <name>_<version>_<arch>.qpkg
```

Keys of `qpkg.cfg` the template sets:

| Key | Meaning |
|---|---|
| `QPKG_NAME` | the name in App Center and in `/etc/config/qpkg.conf`: at most 20 characters, letters, digits, `-`, `_` |
| `QPKG_DISPLAY_NAME`, `QPKG_SUMMARY`, `QPKG_AUTHOR` | what App Center shows |
| `QPKG_VER` | the version, at most 10 characters. `qbuild` cuts a longer one ("value truncated") and writes the cut value into `qpkg.cfg`: `0.16.22-100` would ship as `0.16.22-10` and install as a downgrade |
| `QPKG_RC_NUM` | the order among packages at boot (lower starts earlier) |
| `QPKG_SERVICE_PROGRAM` | the service script's name |
| `QTS_MINI_VERSION` | the lowest firmware that installs it. `5.2.10` lets QuTS hero 6.x install it, since hero reports that number; a program that needs QTS 6.0 checks the real floor itself when it starts |

A package with a web page adds the keys of App Center's Open link, as Bucket & Code Server IDE's own `qpkg.cfg`
does: `QPKG_WEBUI` (the path, `/`), `QPKG_WEB_PORT` (the HTTP port) and `QPKG_WEB_SSL_PORT` (the HTTPS port).

**Set both ports, not just `QPKG_WEB_SSL_PORT`.** App Center's Open button builds the package's link the same way
it reached QTS itself: over `http://<NAS>:<QPKG_WEB_PORT><QPKG_WEBUI>` when App Center's own page was reached over
plain HTTP, over `https://<NAS>:<QPKG_WEB_SSL_PORT><QPKG_WEBUI>` when it was reached over HTTPS. A package that
sets only `QPKG_WEB_SSL_PORT` has no listener on `Web_Port` at all, and the plain-HTTP case then reaches QTS's own
web server instead of the package: a `403` for a page at `/`, a `404` for one under a path such as `/admin/`,
never the package's own program (measured on two of Bucket & Code Server IDE's example packages).
Give the package a plain-HTTP listener on `Web_Port` that redirects every request to the same path on
`Web_SSL_Port` (a `301` or `307`, built from the request's own `Host` header, never a fixed name), the way Bucket
& Code Server IDE's own web server does. A package whose page is served over plain HTTP only (no HTTPS
listener of its own, such as the *arr apps) sets `QPKG_WEBUI` and `QPKG_WEB_PORT` and leaves `QPKG_WEB_SSL_PORT`
out, as QNAP's own Qsirch and img2pdf do on QTS 6.1 (`Web_Port` 5027 and 5023, no `Web_SSL_Port`); never the same
number in both keys. A package with no web page at all sets none of these three keys, and App Center shows no Open
button for it, which is fine and needs no redirect.

## The service script

**Commands on PATH for a login shell.** QTS makes `/root` anew at every boot, so a package that wants its programs
found by name in an SSH login adds, at every start, one line to `/root/.profile` that reads a profile file of its
own, takes the line out again at every stop, and once more when the package is removed (`PKG_POST_REMOVE` in
`package_routines`). A short command can instead be a link in `/usr/bin`, made and removed the same way (below):

```sh
LINE='[ -f "/usr/app/myapp/etc/profile" ] && . "/usr/app/myapp/etc/profile"'
grep -qxF "$LINE" /root/.profile 2>/dev/null || echo "$LINE" >>/root/.profile
```

The profile appends the package's `bin` and `sbin` to `PATH` (after QTS's own directories, so a QTS command of the
same name still wins). The App Builder's Export as QPKG writes both for you.

QTS runs it as root with `start`, `stop` and `restart`, at boot and shutdown and when the package is switched on or
off. The wizard's QPKG template renders its script from blocks (`service.json`, the Project view's "Service and
package" card) onto a library the package carries, `shared/lib/bvs-qpkg.sh`, whose functions (`qpkg_link`,
`qpkg_daemon_start`, `qpkg_wait_port`, `qpkg_cron_add`, ...) a script of your own can source too. Written by hand,
the same contract looks like this for a daemon (the way Bucket & Code Server IDE's own service script starts and
stops its daemon):

```sh
#!/bin/sh
CONF=/etc/config/qpkg.conf
QPKG_NAME="mysvc"
QPKG_ROOT=$(/sbin/getcfg "$QPKG_NAME" Install_Path -f "$CONF")
case $0 in # restart runs this file again, after the cd below
  /*) SELF=$0 ;;
  *) SELF=$PWD/$0 ;;
esac
cd / || exit 1
BIN="$QPKG_ROOT/bin/$QPKG_NAME"
LINK="/usr/bin/$QPKG_NAME"        # the command on PATH: made at every start, taken away at every stop
PIDFILE="/var/run/$QPKG_NAME.pid" # on the RAM disk: a reboot clears a stale one
LOG="$QPKG_ROOT/$QPKG_NAME.log"

running() { # sets pid when the PID file names a process that runs our program
  pid=$(cat "$PIDFILE" 2>/dev/null)
  [ -n "$pid" ] || return 1
  [ "/proc/$pid/exe" -ef "$BIN" ] && return 0
  case "$(readlink "/proc/$pid/exe" 2>/dev/null)" in # an upgrade replaced the file while it ran
    *"/.qpkg/$QPKG_NAME/bin/$QPKG_NAME (deleted)") return 0 ;;
  esac
  return 1
}

case "$1" in
  start)
    if [ "$(/sbin/getcfg "$QPKG_NAME" Enable -u -d TRUE -f "$CONF")" = "FALSE" ]; then
      echo "$QPKG_NAME is disabled."
      exit 1
    fi
    if [ -L "$LINK" ] || [ ! -e "$LINK" ]; then # only a link is ever replaced, never a file of another
      ln -sfn "$BIN" "$LINK"
    fi
    running && exit 0
    (trap '' HUP && exec "$BIN" </dev/null >>"$LOG" 2>&1) &
    echo $! >"$PIDFILE"
    ;;
  stop)
    if running; then
      kill "$pid"
      n=0
      while [ -d "/proc/$pid" ] && [ "$n" -lt 20 ]; do
        sleep 1
        n=$((n + 1))
      done
      [ -d "/proc/$pid" ] && kill -9 "$pid"
    fi
    rm -f "$PIDFILE"
    [ "$(readlink "$LINK" 2>/dev/null)" = "$BIN" ] && rm -f "$LINK" # only while it is still our own link
    ;;
  restart)
    "$SELF" stop || exit # the failing step's status; no start after a failed stop
    "$SELF" start || exit
    ;;
  status)
    if running; then echo "$QPKG_NAME is running."; else echo "$QPKG_NAME is stopped."; fi
    ;;
  enable)
    /sbin/setcfg "$QPKG_NAME" Enable TRUE -f "$CONF" || exit 1
    echo "$QPKG_NAME: auto launch enabled (Enable = TRUE)"
    ;;
  disable)
    /sbin/setcfg "$QPKG_NAME" Enable FALSE -f "$CONF" || exit 1
    echo "$QPKG_NAME: auto launch disabled (Enable = FALSE), the next start is refused"
    ;;
  *)
    echo "Usage: $0 {start|stop|restart|status|enable|disable}"
    exit 1
    ;;
esac
exit 0
```

- QTS runs `start` on every installed package at boot, switched-off ones too: `Enable` in `qpkg.conf` decides
  whether the package starts, and the `Enable = FALSE` test is what keeps a switched-off package down; a missing key
  counts as enabled. Test it first, before `start` makes anything. `start` never writes the flag: only App
  Center's switch, `enable` and `disable` do. `enable` and `disable` write only that flag, for use over SSH: they
  neither start nor stop the program.
- `cd /` at the top, before the script runs anything: QTS's installer runs `start` in the package's temporary install
  folder (`<volume>/.qpkg/.tmp-<QPKG_NAME>`) and deletes that folder when the install ends. Every process started
  there keeps the deleted folder as its working folder (`readlink /proc/<pid>/cwd` ends in `(deleted)`), and a
  program that asks for its working folder, or whose child does, fails: git says "Unable to read current working
  directory". Use absolute paths only, and make `$0` absolute before the `cd` when the script runs itself again, as
  `restart` does. A script that sources `bvs-qpkg.sh` gets the `cd /` from `qpkg_init`.
- The PID file lives on the RAM disk, and `stop` kills only a process whose program is `$BIN`, or was `$BIN`
  before an upgrade replaced the file (the link then ends in `(deleted)`). A PID file kept on the volume would
  outlive a power cut, and its number could by then belong to another process.
- Redirect the output yourself and keep the log on the volume. `trap '' HUP` keeps the daemon alive when you run
  the script from an SSH login and log out.
- Write it for the NAS's `/bin/sh` and BusyBox, with full paths (`/sbin/getcfg`). The GNU tools of the editor's terminal
  are not there when QTS runs it (see [nas-shell.md](nas-shell.md)).
- Anything you place on the RAM disk (a link in `/usr/bin`, a file in `/etc`) is gone after a reboot. Make it in
  `start`, after the `Enable` test, under a fixed name, replacing only a link (never a file or a folder of another);
  take it away in `stop`, and only while it is still yours (a link to your own target), as the template does with
  `/usr/bin/<name>`. A stopped or switched-off package leaves the root file system as it found it.
  `PKG_POST_REMOVE` in `package_routines` takes it away once more when the package is removed.
- Keep data and logs under `$QPKG_ROOT` or in a shared folder, never in `/tmp`. Keep settings with
  `setcfg "$QPKG_NAME" <Key> <Value> -f /etc/config/qpkg.conf`.
- Report to the NAS's System Logs with `/sbin/log_tool -t 0|1|2 -a "…"`.
- Ship every tool the firmware does not have inside the package (static, or built with the App Builder's `bundle`
  or `static` mode); the firmware's own tools listed in [nas-shell.md](nas-shell.md) can be called by full path.
  Do not call `/usr/bin/bucketvs/bin/…`: your package must also run where Bucket & Code Server IDE is not
  installed.

## Building the package

### On your own computer

QNAP publishes QDK 2.5.0 as a Debian package. Check its sha256 before you install it; `apt-get` then also installs
what `qbuild` calls, since `rsync`, `openssl` and `bsdextrautils` (`hexdump`) are among the package's dependencies:

```sh
curl -fLO https://github.com/qnap-dev/QDK/releases/download/v2.5.0/qdk_2.5.0_amd64.deb
echo '66ea6ac9c0de90959395f35ff6cd706fffb09fd92038a16dc50e99927df087a7  qdk_2.5.0_amd64.deb' | sha256sum -c
sudo apt-get install ./qdk_2.5.0_amd64.deb   # on the computer; qbuild is /usr/share/QDK/bin/qbuild (/usr/bin/qbuild links to it)
cd <the package folder>
qbuild                                       # --build-arch x86_64 or arm_64 builds for one processor
ls -l build/                                 # check the package's size after every build
```

- The same release has `qdk_2.5.0_arm64.deb` for an ARM64 computer, sha256
  `c30187b40edf27c6f1f2213bb2b3558344b89667f07f2b40ea041f4612ec0899`.
- `dpkg -i` does not install the dependencies, and without `rsync` `qbuild` exits 0 with a package that has no
  files.
- `qbuild --7zip` calls `/usr/local/sbin/7z` by that full path, not from `PATH`. Without it `qbuild` still exits 0
  and writes a `.qpkg` with no payload: on a bare Ubuntu 24.04 system it wrote 28 KB instead of 8.4 MB and
  reported success. Install 7-Zip and link it there: `sudo apt-get install 7zip && sudo ln -s "$(command -v 7z)"
  /usr/local/sbin/7z`. The default compression, gzip, does not use 7z.
- Keep `QPKG_VER` at ten characters or fewer (the table above).

### In Bucket & Code Server IDE

```sh
bvs tc install qdk-2.5.0-x86_64    # once, an admin; qdk-2.5.0-aarch64 on an ARM NAS
cd <the package folder>
bvs qbuild                         # --env <name> picks the environment; other arguments go to qbuild
```

- `bvs qbuild` runs QDK's `qbuild` inside a Debian or Ubuntu environment (`ubuntu2404-builder`, else `debian12-builder`, else the first one)
  with the folder at `/work`. The catalog's QDK does not run on QTS itself: there its `qbuild` looks for an App
  Center QDK in `qpkg.conf` and calls the NAS's own `/bin` programs by full path.
- The environment needs `bash` and `rsync`. Without `rsync`, `qbuild` would write a package with no files;
  `bvs qbuild` refuses first and names the `apt-get install` that fixes it.

## Code signing and publishing

- `bvs qbuild` first says which of the three signing cases applies: the files `certificate` and `private_key` next
  to `qpkg.cfg` (case 1, signed with `openssl`; the environment also needs `bsdextrautils`), a key on a USB token
  or an HSM (case 2, `certificate_hsm`, with the token plugged into the NAS: from 1.0.0-73 on x86_64), or none
  (case 3, unsigned). Details, the CI recipes and QDK's own token route: [signing.md](signing.md).
- `qbuild` on your own computer signs the same way when `certificate` and `private_key` lie next to `qpkg.cfg`
  ([signing.md](signing.md)).
- `bvs repo publish build/<file>.qpkg [--latest]` puts a signed package into the package repository, which App
  Center on other NAS units reads. Without Bucket & Code Server IDE, a `repo.xml` on a web server does the same:
  [app-center-and-repos.md](app-center-and-repos.md).
- App Builder's Export as QPKG writes unsigned packages: the NAS holds no code-signing certificate.

## Installing for a test

Use App Center's manual install, or on the NAS `qpkg_cli -m /share/<folder>/<file>.qpkg --keep`. Without `--keep`
(`-K`) `qpkg_cli -m` deletes the file after it installs it (QTS 6.1's usage text says so; QuTS hero 6.0's
`qpkg_cli` has the same `--keep`). `qpkg_cli --start <name>`,
`--stop <name>`, `-s <name>` (status) and `-R <name>` (remove) manage it afterwards. Copy the file to a shared
folder first, not to `/tmp`: from your own computer over SMB or SFTP, or with
`scp build/<file>.qpkg <account>@<NAS>:/share/<folder>/`. Running `sh <file>.qpkg` installs it as unsigned, and App
Center then disables it. For an unsigned package, `qpkg_cli -m` installed nothing on a QTS 6.1 unit ([signing.md](signing.md), case 3).

## Sources

The QDK install, the `--7zip` and `QPKG_VER` findings and the copy to a shared folder were measured while building
QPKGs with QDK 2.5.0 on Ubuntu 24.04 for QTS 6.1 and QuTS hero 6.1 units. QDK 2.5.0 (its `qbuild`, its
`--create-env` template, its Debian package's dependencies and its `qpkg.cfg` template), Bucket & Code Server IDE's own `qpkg.cfg` and service script,
its user guide (`bvs guide`, "Building a QPKG with bvs qbuild"), and QNAP Club Poland's
[help-qts61.txt](https://forum.qnap.net.pl/llms/help-qts61.txt) for `qpkg_cli`'s usage.
