Repository navigation
Host helper
On Unraid, the scheduled-task files and some plugin settings are readable by root only. The bot runs as a normal user in its container, so it cannot read them. The host helper is a small Python program that runs as root on the server and reads these files for the bot. The bot asks for the data over a Unix socket, which is a file that two programs on one machine use to talk.
The helper is optional. Without it, the Tasks section shows needs the shazzzbot helper, and the UPS row shows no shutdown setting.
The bot asks the helper for these actions only:
| Action | Data |
|---|---|
hello |
The helper version, the SHA-256 of the running helper file, the protocol number, the bundle version, and the SHA-256 of the startup entry file. It is always on. The System section uses it for the node status. |
tasks |
The name and schedule of each cron job and User Scripts schedule, the tasks that run now, the finish times and run times of finished tasks, the unacknowledged SMART warnings, and the new Unraid version when the OS update check found one. |
ups_shutdown |
The shutdown setting of the Unraid NUT plugin, from /boot/config/plugins/nut-dw/nut-dw.cfg. The bot asks for it only when [ups] target is set. |
The tasks data never contains the command lines of the jobs, because a command line can contain a password.
- Unraid. The helper stops if
/etc/unraid-versiondoes not exist. - Python 3.11 or later at
/usr/bin/python3. Unraid does not include Python. In Apps, search for Python 3 for UNRAID and install it. - The User Scripts plugin. The directory
/boot/config/plugins/user.scripts/scriptsmust exist. - An
appdatashare on a pool (for examplecache) with thexfs,btrfs,zfs, orext4file system. The helper directory cannot be on an array disk. - The flash drive must have no writable SMB share and no writable NFS export (see Security model).
- All commands on this page run as
root.
The helper keeps everything that it owns in three places:
| Place | Path | Content |
|---|---|---|
| Helper directory | /mnt/<pool>/appdata/shazzzbot-helper |
config.json, api.key, policy.json, helper.pyz, helper.pyz.prev, shazzzbot-helper-unraid.py, helper-unraid.json, .identity.json, helper.log, helper.log.1, and the transactions directory of setup.sh. |
| Startup hook | /boot/config/plugins/user.scripts/scripts/shazzzbot-helper/ |
The script, name, and description files of one User Script, and its entry in /boot/config/plugins/user.scripts/schedule.json. |
| Work directory | /tmp/shazzzbot-helper |
runtime/helper.pyz, a copy of the helper in memory, and socket/, which holds helper.sock, helper.pid, and lock files. |
The owner of the helper directory must be root, and its mode must be 700. The owner of each file in it must be root, and the file must give no permission to the group or other users. setup.sh finds the pool from /mnt/user/appdata/shazzzbot-helper. To use a different directory, set SHAZZZBOT_HELPER_DIR before you run setup.sh.
Unraid keeps /tmp in memory and clears it at each reboot. The startup hook makes the work directory again.
To remove the helper, delete the helper directory or turn off the schedule of the User Script. The running helper sees the change within about 1 second, prints helper disabled; installation or startup hook is unavailable, and stops.
setup.sh installs the helper. It is the only supported installation method. See Installation for how to get setup.sh.
-
On the server, run one of these commands as
root:./setup.sh --helper # install or update the bot and the helper ./setup.sh --helper-only # install or update only the helper
-
Answer the questions.
setup.shasks before it schedules the helper and before it starts the helper. -
Connect the bot to the helper (see Bot settings).
setup.sh does these steps:
- It checks the requirements and the flash drive shares.
- It downloads the helper files of the release and makes sure that each SHA-256 agrees with
release.jsonof that release. - It makes the helper directory,
config.json, andapi.key. It keeps aconfig.jsonand anapi.keythat already exist. - It writes
policy.json, which holds the SHA-256 ofhelper.pyz, and installs the helper files. - It writes the startup hook and runs the Configuration check.
- It adds the hook to the User Scripts schedule with the frequency
boot. Without this entry, the helper does not start. - It starts the helper.
- For a bot that
setup.shinstalled, it writesSHAZZZBOT_HELPER_KEYandHELPER_SOCKET_DIRinto the.envfile of the bot.
Note
To install from a local bundle, build it with python3 tools/build_helper.py --bundle-dir DIR --version vX.Y.Z --revision FULL_SHA. Then add --helper-bundle DIR to the setup.sh command. setup.sh then downloads no helper files.
A writable flash share stops the installation, unless you add --accept-flash-share. When setup.sh makes config.json, this option also sets accept_flash_share to true.
Warning
With --accept-flash-share, any person who can write to the flash share can run code as root.
setup.sh writes config.json from helper.example.json. The helper refuses an unknown key and a value of the wrong type.
| Key | Default | Description |
|---|---|---|
format |
none, required | The format of the file. It must be 1. |
enabled |
[] |
The actions that the helper serves, in addition to hello. setup.sh writes ["tasks", "ups_shutdown"]. |
peer_uids |
[] |
The user ids that can connect. The bot runs as user id 10001, and helper.example.json has [10001]. |
socket_uid |
0 |
The owner of the socket file. 0 or more. |
socket_gid |
10001 |
The group of the socket and of its directory. It must agree with HELPER_GID in the .env file of the bot. For a bot that setup.sh installed, setup.sh copies HELPER_GID from that file. |
read_timeout |
5 |
Seconds that the helper waits for a request, and for each write of an answer. 1 or more. |
action_timeout |
300 |
Seconds that one action can run, from 1 to 86400. A read action has a limit of 5 seconds. When the helper stops, it waits this long for running actions. |
output_bytes |
65536 |
The maximum size of one answer, from 1 to 1048576 bytes. |
log_bytes |
1048576 |
The maximum size of the log in memory and of helper.log, from 4096 to 16777216 bytes. |
flush_minutes |
60 |
Minutes between writes of the log to helper.log. 1 or more. |
release_url |
The GitHub latest-release API URL of the project | Where the helper looks for a newer version. It must start with https://. |
update_url |
"" |
The HTTPS URL of a new helper.pyz, for --update. |
update_sha256 |
"" |
The SHA-256 of the new helper.pyz, for --update. 64 hexadecimal digits. |
update_version |
"" |
The version of the new helper.pyz, as MAJOR.MINOR.PATCH, for --update. |
accept_flash_share |
false |
true lets the helper run while the flash drive has a writable share. |
key_file, log_file, installation_policy, and socket
|
Fixed paths | These must be api.key, helper.log, and policy.json in the helper directory, and /tmp/shazzzbot-helper/socket/helper.sock. The startup hook also needs key_file, installation_policy, and socket written in the file. setup.sh writes them. |
scripts, script_binaries, and userscript_allow
|
Empty | Settings for action families that the bot does not use. Leave them empty. |
_comment |
"" |
Free text. The helper ignores it. |
api.key holds the shared key. Its content must be 32 or more letters, digits, _, or -. setup.sh writes 64 hexadecimal digits.
The helper reads config.json when it starts. After a change, stop the helper and start it again (see Stop and start).
Warning
The helper also has action families that change the server: vm, stack, container, parity, smart, script, and userscript. The bot never sends them. Do not add them to enabled. In enabled, they are open to any program with the key and an allowed user id.
For a bot that setup.sh installed, setup.sh writes the .env values. It adds the [helper] table only when it makes a new config.toml and the helper key already exists. In other cases, do these steps:
-
Put these lines in the
.envfile of the bot:SHAZZZBOT_HELPER_KEY=<the content of api.key> HELPER_SOCKET_DIR=/tmp/shazzzbot-helper/socket
-
Make sure that
HELPER_GIDin.envis the same assocket_gid. Both defaults are10001. -
Add this table to
config.toml:[helper] socket = "/run/shazzzbot-helper/helper.sock" key_env = "SHAZZZBOT_HELPER_KEY"
-
Recreate the bot container:
docker compose up -d --force-recreate shazzzbot
The [helper] table needs both keys and no others (see Helper). socket is the path inside the bot container, where Compose mounts HELPER_SOCKET_DIR at /run/shazzzbot-helper. It must be an absolute path of at most 107 bytes. key_env holds the name of the environment variable that holds the key. If that variable is not set or the key is not valid, the bot does not start.
To show the UPS shutdown setting, also set [ups] target in config.toml (see UPS).
The startup hook starts the helper. It accepts no option or one of these options:
| Option | Effect |
|---|---|
| none | Starts the helper. |
--check |
Does the Configuration check, then stops. |
--update <sha256> |
Replaces helper.pyz of the running helper (see Updates). The SHA-256 must be in lowercase. |
The hook waits up to 30 seconds for the pool of the helper directory. If the pool is not mounted, it prints helper storage is not mounted; nothing started. If a check of the hook fails, it prints helper hook refused and stops with exit code 1.
The helper refuses to start from helper.pyz in the helper directory, and prints helper failed: ValueError. Always start it through the hook.
Run the startup hook with --check:
bash /boot/config/plugins/user.scripts/scripts/shazzzbot-helper/script --checkThe hook checks the helper files, their SHA-256, and the hook schedule. Then the helper checks config.json, the key, the work directory, and the flash drive shares, and stops. When all is correct, it prints the actions that it serves and stops with exit code 0:
enabled: hello tasks ups_shutdown
When a check fails, the command prints helper hook refused, or helper failed: and the name of the error, for example helper failed: ValueError. Then it stops with exit code 1. The usual causes are these:
- The command does not run as
root. - A file in the helper directory has the wrong owner or permissions.
-
config.jsonhas an unknown key, a wrong value, or a path outside the helper directory. - The SHA-256 of
helper.pyzdoes not agree withpolicy.json. - The hook is not in the User Scripts schedule.
- The flash drive has a writable share, and
accept_flash_shareisfalse.
To stop the helper, send it the stop signal. Its process id is in helper.pid:
kill -TERM "$(python3 -c 'import json; print(json.load(open("/tmp/shazzzbot-helper/socket/helper.pid"))["pid"])')"The helper waits up to action_timeout seconds for running actions, writes its log, and removes the socket.
To start the helper, open Settings > User Scripts and click Run in Background on the shazzzbot-helper script.
The helper keeps its log in memory and writes it to helper.log every flush_minutes minutes and when it stops. Each line starts with a UTC time stamp, and the helper also prints each line to its standard output. The helper replaces the key with [redacted] in each line.
When the file would become larger than log_bytes, the helper renames it to helper.log.1 and starts a new file. Typical lines are these:
2026-01-01T00:00:00Z startup version=0.1.0 sha256=<sha256>
2026-01-01T00:00:10Z action tasks target=host
2026-01-01T00:00:10Z done tasks target=host rc=0
2026-01-01T00:00:20Z request refused
| Line | Meaning |
|---|---|
request refused |
A request had a wrong user id, a wrong signature, a time stamp more than 30 seconds from the clock of the helper, a used one-time value, or an action that is not in enabled. A writable flash share also causes it. |
protocol mismatch expected=<n> received=<n> |
The bot and the helper use different protocol versions. Update the helper. |
tasks collection failed (<error>) |
The helper could not read the task data. |
startup update check unavailable |
The helper could not read release_url. |
update available ... |
A newer release exists. The line tells what to do. |
helper disabled; installation or startup hook is unavailable |
A file of the helper or the hook schedule is missing or changed, so the helper stopped. |
log flush failed; retaining RAM log |
The helper could not write helper.log. It keeps the log in memory. |
When it starts, the helper reads the latest release at release_url. When that release is newer than the helper or its bundle, the log shows update available and the next step. The helper repeats this line every flush_minutes minutes. The /update command of the bot also shows the helper version.
To update all helper files, run setup.sh again on the server:
./setup.sh --upgrade --helpersetup.sh stops the helper, keeps the old file as helper.pyz.prev, installs the new files, does the configuration check, and starts the helper again. When the installed helper is current, it changes nothing. ./setup.sh --helper-only updates only the helper.
The --update option replaces only helper.pyz of a running helper. It does not update the startup entry file. Do these steps:
-
Put the new
helper.pyzon an HTTPS server, and setupdate_urlto its URL. -
Set
update_sha256to the SHA-256 of the file, andupdate_versionto its version. -
Run the startup hook with the same SHA-256:
bash /boot/config/plugins/user.scripts/scripts/shazzzbot-helper/script --update <sha256>
The helper downloads the file over HTTPS within 30 seconds. The file can be at most 1 MiB. The helper makes sure that its SHA-256 agrees with update_sha256, that its version agrees with update_version, and that this version is newer. It keeps the old file as helper.pyz.prev, and the running helper starts the new file. If the new file does not start in 30 seconds, the helper puts the old file back. When the update succeeds, the command prints manual update <old> -> <new>.
Compose mounts HELPER_SOCKET_DIR into the bot container, read-only. Compose does not start the bot when HELPER_SOCKET_DIR is not set. setup.sh always sets it to /tmp/shazzzbot-helper/socket. When the directory does not exist, Docker makes it, so the bot starts with or without the helper.
Without the helper, do not add a [helper] table to config.toml. Then the Tasks section shows needs the shazzzbot helper as a normal row. With a [helper] table and no running helper, that row and the helper node show a warning.
The helper runs as root, so it limits who can talk to it and what it does:
-
Private storage. The helper directory is on a pool, with owner
rootand mode700. The helper refuses a file in it that the group or other users can access. It never makes its directory on a pool that is not mounted. -
Verified start. The startup hook checks the SHA-256 of the hook, of its entry file, and of
helper.pyzagainst the recorded values. It runs a copy ofhelper.pyzfrom the work directory in memory. - Supervision. Every second, the helper checks its files, the hook, and the hook schedule. When a check fails, it stops and cancels the running actions.
-
Socket access. The socket directory has mode
750, with ownerrootand groupsocket_gid. The socket has mode660. The helper also checks the user id of each connection againstpeer_uids, and it accepts at most 64 connections at a time. - Signed requests. Each request carries an HMAC-SHA256 signature made with the shared key, a time stamp, a one-time value, and a protocol number. The helper refuses a request with a wrong signature or a time stamp more than 30 seconds from its clock. It also refuses a one-time value that it saw in the last 61 seconds. A request can be at most 4096 bytes.
-
Root check by the bot. The bot connects only when the other end of the socket runs as
root. The bot can send only thehello,tasks, andups_shutdownactions, with no arguments. It waits at most 15 seconds for an answer. -
Fixed reads. The read actions take no arguments and read fixed paths only. They skip files and directories that
rootdoes not own, or that the group or other users can write. Each file can be at most 1 MiB, and onetasksread at most 8 MiB. -
Flash share check. The startup hook is on the flash drive. A writable flash share or NFS export would let a person on the network change a file that
rootruns. Thus the helper does not start, and refuses each action, while the flash drive is writable over the network. -
Pinned updates.
--updatedownloads only over HTTPS, and only a file with the SHA-256 and the version inconfig.json. The version must be newer.
The helper never reboots or shuts down the server, and it never starts or stops the array.