PushWard Unraid Plugin

Beta: expect rough edges, and please report issues.

A self-contained Unraid plugin that connects your server to PushWard. It does three things.

Notifications. Every Unraid notification is forwarded to your phone.

Live Activities. Long-running jobs (parity check/rebuild, appdata backup, mover, VM backup, UPS on battery) show real-time progress on the Lock Screen and Dynamic Island, with a dashboard page to view and end them.

Home Screen widgets. Optional: array fill, free space per disk and pool, and a status list. Off by default.

It installs a native notification agent plus a small monitor that reads Unraid's own state. There is no downloaded binary and no Unraid API key to manage; everything talks to the PushWard REST API over HTTPS.

Install

In the Unraid web UI, open Plugins > Install Plugin and paste:

https://github.com/mac-lucky/pushward-unraid-plugin/raw/main/pushward-unraid.plg

Needs Unraid 6.12 or later.

Configure

Open Settings > PushWard (in the User Utilities row) and, on the Settings tab, fill in:

Click Apply, then use the test buttons to confirm each path. The Settings tab shows live status: whether the key is valid, whether the subscription is active, and whether the monitor is running.

API key permissions

One hlk_ key can carry all three:

• Notifications need the notifications capability.
• Live Activities need activity:manage scope and an active PushWard subscription.
• Home Screen widgets need the widgets capability. Without it the widget calls come back 403 and the log says so; nothing else is affected.

Notifications work without a subscription; creating and updating Live Activities does not.

What it does

Notifications

The agent lives at /boot/config/plugins/dynamix/notifications/agents/PushWard. Unraid invokes it for every notification whose importance has the Agent method enabled (Warning and Alert by default; enable Info too under Settings > Notifications). The full message body is forwarded, not just the subject.

Unraid has three importances. An ALERT becomes whatever "Alert notification level" is set to, Time Sensitive out of the box; a WARNING becomes a Normal push; anything else stays passive. A subject starting Alert [ or Warning [ raises the level to match whatever importance it arrived with, and never lowers it - Unraid sends a parity check that finished with errors as Notice [...] at Warning importance. Critical is the level that breaks through Do Not Disturb and the silent switch, so it is opt-in, and it needs the critical-alert permission granted to the PushWard app.

Repeats of the same event replace the previous banner rather than stacking, keyed on the server name and the event, so a SMART warning that repeats every hour leaves one banner. Notifications Unraid files under "Unraid Status", which is what User Scripts and many plugins send when they name no event, are keyed on their subject as well, so unrelated ones keep their own banners. The app's notification list still holds every one of them. A notification about a job the monitor is already tracking carries a link to that Live Activity.

Repeat until acknowledged

Off by default. Switch on "Repeat alerts until acknowledged" and every notification that arrives as an Unraid Alert comes back every 300 seconds (or whatever you set) until you tap Acknowledge on one of your devices, or until the stop time passes, an hour by default. Warnings and info never repeat. "Send test notification" sends an Alert, so it is an easy way to try it. Switching the setting off only affects new alerts: the ones already repeating carry on until acknowledged or until their stop time.

Each repeating alert is tagged unraid-<server name>, lowercased with dashes, so pushward receipt cancel --tag unraid-tower from the PushWard CLI stops them all; a tag only reaches what the same API key sent. It also gets a second tag hashed from the server and the event, and when a notification for that event arrives that is not an alert, like Unraid's "returned to normal", the plugin cancels the alert's repeats before sending it, so a late repeat cannot cover the good news. Notifications sent without an event name of their own, which Unraid files under "Unraid Status" (User Scripts and many plugins do this), are told apart by their subject instead and never cancel anything. An account holds at most 25 repeating alerts at once. Past that, or when PushWard turns acknowledged alerts off for a while, the plugin sends the alert once as an ordinary notification rather than lose it.

End-to-end encryption

With a key set, the agent encrypts the title, subtitle, body and link of every notification on the box before it is sent. PushWard stores and forwards an envelope it cannot open, and your devices decrypt it with the same key.

1. In the PushWard app (1.17 or later), open Settings > End-to-End Encryption, create a key and copy it.
2. Paste it into "End-to-end encryption key" and click Apply. The status cards show its Key ID, which should match the one in the app.

The page never shows the stored key: leaving the field empty keeps it, pasting another one replaces it, and "Remove key" turns encryption off. An hlk_ API key pasted there is refused.

PushWard still reads the level, the server name, the timestamp and the importance, the name of the Live Activity a notification links to (tower-array, tower-backup, tower-vmbackup), and the repeat settings and tags when those are on (unraid-tower names the server). The event name is replaced by a hash keyed with your encryption key, so repeats of one event still replace each other's banner, but the hash cannot be matched against a list of likely event names. A link is encrypted only as a full http:// or https:// address: a web UI path gets the "Unraid web UI URL" in front of it, or is left out when that is unknown. The envelope fits about 2.2 KB of text, so a long message is shortened, the body first. Live Activities and widgets are not encrypted at all, so the jobs they track are visible to PushWard either way.

If the key is not valid, or PHP on the box has no AES-256-GCM, notifications still go out but without the details ("Unraid alert on Tower", with a body saying which of the two it is), the syslog says why, and the Encryption card on the Settings tab turns red. With an API key that belongs to an organization, paste the organization's key instead of your own: the organization's admin creates it and hands it out, and members read the notifications once they add it in PushWard 1.18 or later under Settings > End-to-End Encryption > Organization Keys (docs). If PushWard has encryption for organizations switched off, it refuses the encrypted send, so the plugin sends the content-free alert instead and the syslog says why. A device without the key, or with an app older than 1.17, shows "Encrypted notification" in place of the text.

Live Activities

A background monitor, started by an array-event hook and kept alive by a 1-minute watchdog cron, polls Unraid's state and drives PushWard activities:

Activities appear via push-to-start (no app interaction needed), update as the job runs, and end automatically when it finishes. Each card carries an Open button that goes to the matching page in the web UI. View and end the current ones on the Activities tab of Settings > PushWard.

The monitor only reads status; it never touches Unraid or the source plugins. It also stays under PushWard's update quota by pushing only on a meaningful change.

A few notes on the newer sources. Mover lists the files as they move, read from the lines Unraid writes to syslog when "Mover logging" is on (Settings > Scheduler > Mover Settings); with that setting off there are no per-file lines and it shows a progress bar with bytes moved and speed instead. The percent is a fraction of the data the run will move: at the start the monitor measures, once, the size of each share set to move cache to array (Use cache = Yes) on its assigned pool, and uses that as the denominator. It reads only the cache pools, so the array stays spun down. Bytes moved come from how much the pools drain. Both are estimates, since mover skips open or in-use files and new writes refill the cache during a run, so the bar can stall short of full; the run finishing is what marks it complete. When nothing movable is found the bar is indeterminate. VM backup tracks the vmbackup plugin's own scheduled or manual run, and a backup launched through the User Scripts plugin under a custom name is not detected. The UPS source reads apcaccess and only appears while the UPS is on battery; NUT is not supported.

Home Screen widgets

Off by default, because they need an extra permission on your key (see above) and they occupy space in your phone's widget picker whether or not you place them. Switch them on under Settings and the monitor publishes three:

Everything comes from the status files Unraid already keeps up to date, so a refresh never spins a disk up to read it. Widgets refresh on their own interval (default 300s) rather than the activity poll, and re-send unchanged content twice an hour so the app does not grey them out as stale; the server counts that as a touch, not a push, so it costs nothing against your quota. Switching them back off removes them from your account.

Uninstall

Plugins > PushWard > Remove. The agent, monitor, settings/dashboard pages and cron are removed, any active Live Activities are ended, and any published widgets are deleted. Your config under /boot/config/plugins/pushward-unraid/ stays put, so reinstalling restores your API key.