TrueNAS SCALE: USB Speaker Pool-Alert Guide
Hardware noted: ASUS Pro WS WRX80 motherboard, USB speaker: AmazonBasics USB Plug-n-Play Computer Speakers
This guide produces an audible alert through a USB speaker whenever any ZFS pool is not healthy. It avoids installing packages on the TrueNAS host by using a tiny Docker image that contains ALSA’s aplay..
0) Prereqs (one-time)
- TrueNAS SCALE with Apps/Docker enabled.
- USB speaker is plugged in and powered.
- Access to the TrueNAS web UI Shell (root).
Create a folder to hold the alert sound:
sudo mkdir -p /mnt/APPS/alerts
Build a tiny image that has aplay:
cat >/root/alsa-aplay.Dockerfile <<'EOF' FROM debian:bookworm-slim RUN apt-get update && apt-get install -y --no-install-recommends alsa-utils && rm -rf /var/lib/apt/lists/* ENTRYPOINT ["aplay"] EOF
sudo /bin/docker build -t local/alsa-aplay -f /root/alsa-aplay.Dockerfile /root
Tip: If /bin/docker isn’t present on your box, use /usr/bin/docker in the commands below.
1) Make a WAV file and put it in a directory
Option A — Generate a simple 1‑second beep (uses a throwaway container)
sudo /bin/docker run --rm -v /mnt/APPS/alerts:/out debian:bookworm-slim bash -lc '
set -e
apt-get update >/dev/null
apt-get -y install sox >/dev/null
sox -n -r 44100 -b 16 -c 2 /out/pool_degraded.wav synth 1 sine 880
'
Option B — Use your own WAV
Copy any WAV (e.g., a TTS you recorded elsewhere) to:
/mnt/APPS/alerts/pool_degraded.wav
2) Test WAV playback over the USB audio device
List ALSA devices to find your USB speaker (look for “USB” in the card name):
sudo /bin/docker run --rm --device /dev/snd --group-add audio local/alsa-aplay -l
You’ll see entries like:
card 1: USB..., device 0: ...
Use that card,device pair with plughw:<card>,<device>. Test playback (replace 1,0 if your numbers differ):
sudo /bin/docker run --rm --device /dev/snd --group-add audio -v /mnt/APPS/alerts:/audio local/alsa-aplay -D plughw:1,0 /audio/pool_degraded.wav
If you don’t hear anything:
- Try
-D defaultinstead ofplughw:1,0. - Verify the speaker volume and that it’s not muted.
- Re-check the card/device numbers with
-l.
3) Set up a script to play whenever a pool is degraded
Create the alert script:
sudo tee /root/pool_alert.sh >/dev/null <<'EOF' #!/usr/bin/env bash set -euo pipefailCONFIG — adjust these if needed
WAV=“/mnt/APPS/alerts/pool_degraded.wav”
ALSA_DEV=“plughw:1,0” # change if your USB device is a different card,device
DOCKER_IMG=“local/alsa-aplay”
LOG=“/var/log/pool_alert.log” # optional logSanity checks
[[ -f “$WAV” ]] || { echo “Missing WAV: $WAV” | tee -a “$LOG”; exit 0; }
If any pool is NOT healthy, zpool status -x will NOT say “all pools are healthy”
if ! /sbin/zpool status -x | grep -q “all pools are healthy”; then
echo “$(date) : Pool not healthy -> playing alert” >> “$LOG”
/bin/docker run --rm --device /dev/snd --group-add audio -v “$(dirname “$WAV”)”:/audio “$DOCKER_IMG” -D “$ALSA_DEV” “/audio/$(basename “$WAV”)” || true
else
echo “$(date) : Pools healthy” >> “$LOG”
fi
EOF
sudo chmod +x /root/pool_alert.sh
Quick manual test (should play once if a pool is not healthy; otherwise it will just log):
sudo /root/pool_alert.sh && sudo tail -n 3 /var/log/pool_alert.log
Notes
- The script plays once per run. Pair it with a 5‑minute cron to be “annoying” until fixed.
- Edit
ALSA_DEVif your USB device isn’tplughw:1,0. - The check uses
zpool status -xso it works across multi‑pool setups.
4) Make a cron job in the GUI (every 5 minutes)
- Go to System Settings → Advanced → Cron Jobs (in some versions: Tasks → Cron Jobs).
- Click Add.
- User:
root
Schedule: Every 5 minutes (preset or*/5 * * * *)
Command:/root/pool_alert.sh
Description:Play USB speaker alert if any pool is degraded
Enabled: Yes - Click Save.
You should now hear an audible alert every 5 minutes whenever any pool goes non‑healthy.
Troubleshooting
- aplay: device busy / cannot open — Another process may be using the device. Try
-D defaultor confirm the correctcard,devicevia-l. - Cron doesn’t seem to run — In the job details, temporarily disable “Hide Stdout/Stderr” and check for updates in
/var/log/pool_alert.log, or test with/root/pool_alert.sh >> /root/cron_debug.log 2>&1. - New USB device index after reboot — Sometimes the card index changes (e.g., from
1,0to2,0). Re‑check with the-lcommand and updateALSA_DEVin/root/pool_alert.sh.
This was tested on TrueNAS SCALE with an ASUS Pro WS WRX80 board and the USB speaker linked above. If you later want text‑to‑speech instead of a fixed WAV, you can swap the WAV generation step for a small TTS container; the rest (script + cron + aplay) remains the same.
