frugal-iot-server 2.0.11 → 2.0.12

package/docs/INSTALLATION.md

@@ -1164,8 +1164,8 @@ but close enough for sensor data.
 ### Wear and tear on the SD card
 
 SD cards wear out from being written to, and a server recording sensor readings writes all the time.
-We have not yet seen a card fail, but plan for one eventually: keep a copy of `config.d/` and
-`frugal-iot.db` somewhere else, and treat the readings in `data/` as valuable but not irreplaceable.
+We have not yet seen a card fail, but plan for one eventually: see [Backups](#backups), and keep
+the snapshots somewhere other than the card.
 
 A new installation is set up to write as little as it reasonably can, and the settings are worth
 knowing about, because turning one of them back on for debugging and forgetting is easy to do:
@@ -1199,6 +1199,90 @@ and read the **Wear on the SD card** section, which reports how much has been wr
 whether the machine is swapping, and whether each of the settings above is in force. Run it twice a
 few days apart — the interesting number is the rate, not the total.
 
+## Backups
+
+`frugal-iot-backup` takes a snapshot of everything on this machine that cannot be rebuilt: the
+database, `config.d/` (including `secrets.yaml`), the broker's configuration, password file, ACL
+file and TLS certificate, and the server's systemd unit. It finds the broker's files by asking the
+broker's own configuration, so it works however this machine is laid out.
+
+Not in it: `data/` (large, and copied separately - see below), `ota/` (rebuilt at each release),
+and anything the broker rebuilds or is running on.
+
+First see what it would take, and from where - this writes nothing:
+
+```
+cd ~/frugal-iot
+npx --no frugal-iot-backup check
+```
+
+Then take one now, and install a timer that takes one every night:
+
+```
+npx --no frugal-iot-backup
+npx --no frugal-iot-backup install
+```
+
+Both ask for `sudo`, because the broker's files belong to root and to `mosquitto`. Snapshots go to
+`/var/backups/frugal-iot/`, keeping one a day for a week, one a week for a month, one a month for
+three months, one a quarter for a year, and one a year for ever - about 20 small files.
+
+**A snapshot holds every credential this server has** - with it, someone can log in as any node or
+user on the broker. So each one is mode 600, owned by the account the server runs as, in a directory
+nobody else can open. Copy them off the machine the same way: by `rsync` or `scp` as that account,
+to a machine you trust as much as this one.
+
+A snapshot on the same SD card is lost with the card, so it only protects against mistakes. To
+protect against losing the machine, copy `/var/backups/frugal-iot/` and `data/` somewhere else
+regularly - for example from a laptop:
+
+```
+rsync -a pi@frugaliot.local:/var/backups/frugal-iot/ ~/frugal-iot-backups/frugaliot/state/
+rsync -a pi@frugaliot.local:frugal-iot/data/ ~/frugal-iot-backups/frugaliot/data/
+```
+
+Leave out `--delete` on the second: the server may delete old readings to save space, and this way
+the copy keeps them.
+
+`npx --no frugal-iot-diagnostic` reports how old the newest snapshot is, and calls it a problem if
+the timer is installed and nothing has been written for two days.
+
+### Restoring
+
+Restore onto a machine where the server is already installed - after re-flashing a Pi, run the
+installer first, then restore over what it set up. Copy the snapshot onto the machine, then from
+the server's directory see what would happen - this changes nothing:
+
+```
+npx --no frugal-iot-restore <snapshot>
+```
+
+`latest` in place of a file name means the newest one in `/var/backups/frugal-iot/`. Then do it,
+in one of two ways:
+
+* **`state`** - onto a machine its own installer set up, laid out however that is. It restores the
+  database, `config.d/` (including `secrets.yaml`) and the broker's password file, ACL file and
+  account state, each to wherever *this* broker keeps them. It keeps this machine's own broker
+  configuration, TLS certificate, systemd unit, `mqtt.yaml` and `server.yaml`.
+* **`all`** - onto the same machine, or one laid out exactly like it: everything goes back where it
+  came from. Broker configuration files the snapshot does not have are renamed to
+  `<name>.pre-restore`, so the broker does not read both.
+
+```
+npx --no frugal-iot-restore <snapshot> state
+```
+
+If the machine already has logins of its own, add `force` as the last word - it says so rather
+than replacing them silently.
+
+Before changing anything it takes a snapshot of what is there into
+`/var/backups/frugal-iot/pre-restore/`, so a restore can be undone with
+`npx --no frugal-iot-restore <that snapshot> all force`. It stops the server and the broker while it
+works - every node disconnects for a few seconds - and finishes by checking the broker's accounts
+against the database and running the diagnostic.
+
+`data/` is not in a snapshot: copy it back from wherever it is mirrored.
+
 ## Moving the Pi to another WiFi network
 
 This is how to give the Pi a new WiFi network when you cannot log in to it, because it no longer
@@ -1317,7 +1401,8 @@ Two things to know:
 
 If you have not reached step 4 yet, the command does not exist. Copy
 [scripts/diagnostic.zsh](https://github.com/mitra42/frugal-iot-server/blob/main/scripts/diagnostic.zsh)
-to the Pi and run `zsh diagnostic.zsh` instead.
+and [scripts/broker-config.zsh](https://github.com/mitra42/frugal-iot-server/blob/main/scripts/broker-config.zsh),
+which it needs, into the same directory on the Pi and run `zsh diagnostic.zsh` instead.
 
 ### A topic that will not go away
 
@@ -1363,8 +1448,11 @@ sudo systemctl restart frugaliot
 Taking those in turn:
 
 * `npm update` fetches the new version of the server, and of the client and logger it depends on.
+  It may report vulnerabilities, typically in `uuid`. `frugal-iot-init`, next, is what fixes those,
+  so ignore that report and do not run `npm audit fix`.
 * `frugal-iot-init` adds any configuration file or directory the new version expects and you do not
-  have yet. It never changes files you already have, so your settings, database and data are safe.
+  have yet. It never changes your settings, database or data. It also copies the release's
+  dependency `overrides` into your `package.json` and re-runs `npm install` - see below.
 * `systemctl restart frugaliot` is what actually puts the new version into service — without it the
   old one keeps running from memory, and nothing appears to have changed. (Skip this if you are
   running the server by hand rather than as a service; stop it with `Ctrl-C` and start it again.)
@@ -1377,17 +1465,37 @@ journalctl -u frugaliot -n 30
 npm ls frugal-iot-server
 ```
 
-`frugal-iot-init` leaves your own files alone. Two sections of its output are worth reading.
+`frugal-iot-init` leaves your own files alone, with two exceptions, and tells you what differs.
 
-**"These files were left as you have them, but this release ships a different version"** covers the
-sensor schema under `config.d/schema/`, and gives you a `diff` command for each. If you added a
-sensor type of your own, that is exactly what it should say; if you did not, this release changed
-the schema and the difference is worth reading.
+**`package.json`** in the install directory gets the `overrides` section from frugal-iot-server's
+own. These pin transitive dependencies (such as `uuid`, deep below the logger) to versions without
+known vulnerabilities. npm only reads `overrides` from the top-level project, which here is your
+`package.json`, not the package's, so without this step `npm audit` reports problems that a checkout
+of the same release does not. When it adds or changes one it prints `set ./package.json override ...`
+and runs `npm install` to apply it; `npm audit` should then come back clean.
 
-**"Installed elsewhere from extras/, and older than this release"** covers the files that live
-somewhere else — the broker configuration, its ACL, the systemd unit. It compares what is actually
-in `/etc`, not the copy in `extras/`, because that copy is never overwritten and so differs for ever
-once a release changes it. To bring anything it names up to date, re-run the installer:
+**The sensor schema** under `config.d/schema/` is the other. If every line of your copy is still
+in this release's version, all the release did was add to it, so it installs the new one and says
+`updated ... (this release only adds to it)`. If your copy has lines the release does not, it keeps
+yours and shows just those lines: if you added them, that is exactly right; if you did not, this
+release changed or removed them, and it prints the `cp` that takes its version.
+
+**The broker's configuration** is compared setting by setting across every file the broker reads,
+wherever they are - one `frugal-iot.conf` from the installer, or several files in
+`/etc/mosquitto/conf.d/` assembled by hand. Each difference is one line:
+
+```
+  missing:     connection_messages false - not set (mosquitto's default applies)
+  (fine)       password_file - here /etc/mosquitto/mosquitto_passwords (this release's default is /var/lib/mosquitto/passwords)
+```
+
+A file kept at a different path is fine. A `missing:` or `different:` line is something this release
+sets that your broker does not. Add it to any file in `/etc/mosquitto/conf.d/`, then
+`sudo systemctl restart mosquitto` - or, on a Pi set up by `install-pi.sh`, re-run that.
+
+**"Installed elsewhere from extras/, and different from this release"** covers the ACL file and the
+systemd units, found where the broker and systemd say they are. It lists the differing lines,
+marked `here only` and `release only`. To bring them up to date on a Pi, re-run the installer:
 
 ```
 bash node_modules/frugal-iot-server/scripts/install-pi.sh
@@ -1403,29 +1511,18 @@ install these three, because none of them can simply be copied into place:
 | `extras/frugaliot.service` | written for user `pi` in `/home/pi/frugal-iot`; the installer rewrites `User`, `WorkingDirectory` and `ExecStart` for wherever this actually went. |
 
 The setup network's watchdog, `extras/frugaliot-ap-watchdog` and its `.service` and `.timer`, *can* be
-copied as they are; step 8a has the commands. On a Pi installed before the setup network existed,
-re-running the installer adds it, and asks once for the `pi` login's password to give it.
+copied as they are; step 8a has the commands. It is only checked where it is installed. On a Pi
+installed before the setup network existed, re-running the installer adds it, and asks once for the
+`pi` login's password to give it.
 
 The installer will not overwrite an ACL file that has per-bridge rules in it. If this release adds a
 rule to a broker that has them, it says which lines are missing and leaves the file alone for you to
 add them by hand, then `sudo systemctl reload mosquitto`.
 
 > **If your broker's configuration was assembled by hand** — several small files in
-> `/etc/mosquitto/conf.d/` rather than the single `frugal-iot.conf` the installer writes — then
-> `frugal-iot-init` reports those files under "Nothing at the usual place, so these were not
-> compared", and re-running the installer is *not* what you want: it would add `frugal-iot.conf`
-> alongside what you already have, declaring the same listeners and the same plugin twice. Compare
-> by hand instead, and add only what is missing:
->
-> ```
-> sudo grep -hvE '^\s*(#|$)' /etc/mosquitto/conf.d/*.conf | sort -u > /tmp/running.txt
-> grep -hvE '^\s*(#|$)' node_modules/frugal-iot-server/extras/mosquitto.conf | sort -u > /tmp/shipped.txt
-> diff /tmp/running.txt /tmp/shipped.txt
-> ```
->
-> Lines only in the running config are usually this machine's own — TLS `certfile`/`keyfile`, a
-> bridge `listener`, a `password_file` in a different place. Lines only in the shipped one are what
-> this release added.
+> `/etc/mosquitto/conf.d/` rather than the single `frugal-iot.conf` the installer writes — do not
+> re-run the installer: it would add `frugal-iot.conf` alongside what you already have, declaring the
+> same listeners and the same plugin twice. Add the `missing:` and `different:` settings by hand.
 
 > It does not compare `config.yaml`, `config.d/mqtt.yaml`, `config.d/logger.yaml` or
 > `config.d/server.yaml`, because those hold your own settings and would differ every time. If a
@@ -1437,7 +1534,7 @@ which for the settings under [Wear and tear on the SD card](#wear-and-tear-on-th
 goes on writing as often as it did. A server that has been running since before those settings
 existed keeps logging every message and every web request, and writing every reading as it arrives —
 deliberately, since quietening somebody's server without being asked is not a thing an upgrade should
-do. On a Pi, compare the two files above and copy across the settings you want.
+do. On a Pi, compare the files named above and copy across the settings you want.
 
 Your organizations, accounts, database and logged data are untouched by an upgrade — they live in
 this directory, not in `node_modules`.

package/docs/OPENWRT.md

@@ -24,8 +24,8 @@ Run the preflight script (below) and it checks every line of this table for you.
 
 | | Needed | Why |
 | --- | --- | --- |
-| **CPU** | **aarch64 or x86_64.** 32-bit ARM might work. MIPS will not. | OpenWrt's `node` package is only built for some CPUs, and the database module (`sqlite3`) is a compiled binary that has to exist for that CPU and for OpenWrt's C library (musl). Both are most likely on 64-bit. |
-| **Memory** | 512 MB or more (256 MB at the very least) | The server uses about 250 MB once running. |
+| **CPU** | **aarch64 or x86_64.** 32-bit ARM might work. **MIPS will not** (Node.js has no MIPS build at all, so older and cheaper routers - the GL.iNet AR300M, for one - are out). | OpenWrt's `node` package is only built for some CPUs, and the database module (`sqlite3`) is a compiled binary that has to exist for that CPU and for OpenWrt's C library (musl). Both are most likely on 64-bit. |
+| **Memory** | **512 MB or more** | The server alone uses about 250 MB once running, on top of the router's own software. A router with 256 MB cannot do it (a Cudy with 233 MB usable was refused). |
 | **Storage** | **About 400 MB free** on ext4, f2fs or btrfs | The software is ~100 MB; npm needs room to work; readings accumulate. **Most routers' own flash is far too small**, so this means a USB stick or SSD, set up as extroot or just mounted, and `--dir` pointing at it. Not FAT, exFAT or NTFS: the install needs symlinks and Unix permissions. The image may also lack the USB storage driver - see [Preparing the router](#preparing-the-router). |
 | **Node.js** | **20.17 or later**, and npm | From OpenWrt's feed if it has one - **OpenWrt 25.12 has none for aarch64**, in which case it is unpacked by hand from a musl build ([how](#if-the-feed-has-no-node)). The preflight and the installer accept either. |
 | **mosquitto** | A build with **websockets** | The browser dashboard connects over websockets. If the router's mosquitto has none, the dashboard cannot work. |

package/package.json

@@ -12,8 +12,8 @@
     "cookie-parser": "^1.4.7",
     "express": "^5.2.1",
     "express-session": "^1.19.0",
-    "frugal-iot-client": "^2.0.11",
-    "frugal-iot-logger": "^2.0.11",
+    "frugal-iot-client": "^2.0.12",
+    "frugal-iot-logger": "^2.0.12",
     "hash-wasm": "^4.12.0",
     "js-yaml": "^4.2.0",
     "morgan": "^1.11.0",
@@ -28,6 +28,7 @@
     "frugal-iot-server": "frugal-iot-server.js",
     "frugal-iot-init": "scripts/init.zsh",
     "frugal-iot-addorganization": "scripts/addorganization.zsh",
+    "frugal-iot-backup": "scripts/backup.zsh",
     "frugal-iot-setpassword": "scripts/setpassword.zsh",
     "frugal-iot-diagnostic": "scripts/diagnostic.zsh",
     "frugal-iot-clearretained": "scripts/clearretained.js",
@@ -36,6 +37,7 @@
     "frugal-iot-rebuild-dynsec": "scripts/rebuild-dynsec.js",
     "frugal-iot-dynsec-init": "scripts/dynsec-init.js",
     "frugal-iot-resetnode": "scripts/resetnode.js",
+    "frugal-iot-restore": "scripts/restore.zsh",
     "frugal-iot-grafana-token": "scripts/grafana-token.js",
     "frugal-iot-backfill-opensearch": "scripts/backfill-opensearch.js"
   },
@@ -95,7 +97,7 @@
     "check-files": "node scripts/check-published-files.js"
   },
   "type": "module",
-  "version": "2.0.11",
+  "version": "2.0.12",
   "overrides": {
     "uuid": "^11.1.1"
   }

package/public/service-worker.js

@@ -6,7 +6,7 @@
 // it, an installed browser keeps serving the files it already cached - and since the list now covers
 // the dashboard's own code, that means old JS behind freshly fetched HTML. Any edit to the list
 // needs this bumped, or it does not reach anyone who already has the old one.
-const CACHE_NAME = 'frugal-iot-cache-2.0.11';
+const CACHE_NAME = 'frugal-iot-cache-2.0.12';
 /*
  * Everything the app needs, so that a phone on a poor or expensive link fetches it once.
  *

package/scripts/addbridge-prod.zsh

@@ -95,27 +95,23 @@ if [[ "$BRIDGE_CREDENTIAL" == derived ]]; then
   exit 1
 fi
 
-# Which files the running broker actually uses, rather than where they usually are. Only ".conf"
-# files in conf.d are read, and the last setting wins.
-MOSQ_CONFS=(/etc/mosquitto/mosquitto.conf(N) /etc/mosquitto/conf.d/*.conf(N))
-if (( ${#MOSQ_CONFS} == 0 )); then
-  echo "Error: no mosquitto configuration found in /etc/mosquitto" >&2
+# Which files the running broker actually uses, rather than where they usually are - production's
+# configuration is several hand-made files in conf.d. scripts/broker-config.zsh reads each file with
+# sudo when it is root-only; this script needs sudo below anyway, so it may prompt.
+BROKER_SUDO=(sudo)
+source "${0:A:h}/broker-config.zsh"
+broker_conf_read
+if (( ${#BROKER_CONF_FILES} == 0 )); then
+  echo "Error: no mosquitto configuration found at $(broker_conf_main)" >&2
   exit 1
 fi
-# Read one setting out of the broker's configuration. Two things to be careful of: a conf.d file
-# can be root-only (a bridge configuration holds a password, so it should be), which makes grep
-# fail rather than return nothing - and under "set -e" a failing command substitution would end
-# this script silently, before it had printed anything at all. Hence "|| true" and the sudo retry.
-mosq_setting() {
-  local out
-  out=$(grep -hE "^[[:space:]]*$1[[:space:]]" "${MOSQ_CONFS[@]}" 2>/dev/null | tail -1 | awk '{print $2}') || true
-  if [[ -z "$out" ]] && command -v sudo >/dev/null; then
-    out=$(sudo grep -hE "^[[:space:]]*$1[[:space:]]" "${MOSQ_CONFS[@]}" 2>/dev/null | tail -1 | awk '{print $2}') || true
-  fi
-  print -r -- "$out"
-}
-PWFILE=$(mosq_setting password_file)
-ACLFILE=$(mosq_setting acl_file)
+if (( ${#BROKER_CONF_UNREADABLE} )); then
+  echo "Error: could not read ${(j:, :)BROKER_CONF_UNREADABLE}, so cannot tell where the broker" >&2
+  echo "keeps its password and ACL files. Re-run with sudo." >&2
+  exit 1
+fi
+broker_setting password_file; PWFILE="$BROKER_SETTING"
+broker_setting acl_file; ACLFILE="$BROKER_SETTING"
 
 if [[ -z "$PWFILE" ]]; then
   echo "Error: no password_file in the mosquitto configuration - this broker is not using accounts." >&2

package/scripts/addorganization.zsh

@@ -77,9 +77,15 @@ fi
 
 # Ask the broker's own configuration where its password file is, rather than guessing - that way
 # this works whatever layout a machine uses, including installations older than this script.
-# Mosquitto reads /etc/mosquitto/mosquitto.conf and then the .conf files in conf.d, last one wins.
-MOSQUITTO_PASSWD_FILE=$(grep -hE '^[[:space:]]*password_file[[:space:]]' \
-  /etc/mosquitto/mosquitto.conf /etc/mosquitto/conf.d/*.conf(N) 2>/dev/null | tail -1 | awk '{print $2}')
+# sudo may prompt: a Pi's bridge file is root-only, and the password file needs sudo below anyway.
+BROKER_SUDO=(sudo)
+source "${0:A:h}/broker-config.zsh"
+broker_conf_read
+broker_setting password_file; MOSQUITTO_PASSWD_FILE="$BROKER_SETTING"
+if (( ${#BROKER_CONF_UNREADABLE} )); then
+  echo "Warning: could not read ${(j:, :)BROKER_CONF_UNREADABLE} - if the password file is named there," >&2
+  echo "         the one used below may be the wrong one." >&2
+fi
 USED_LOCAL_MOSQUITTO_FILE=0
 if [[ -n "$MOSQUITTO_PASSWD_FILE" ]]; then
   MOSQUITTO_PASSWD_FROM_CONFIG=1