Skip to content

Host helper

Chris edited this page Nov 15, 2026 · 1 revision

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.

Actions

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.

Requirements

  • Unraid. The helper stops if /etc/unraid-version does 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/scripts must exist.
  • An appdata share on a pool (for example cache) with the xfs, btrfs, zfs, or ext4 file 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.

Files

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.

Installation

setup.sh installs the helper. It is the only supported installation method. See Installation for how to get setup.sh.

  1. 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
  2. Answer the questions. setup.sh asks before it schedules the helper and before it starts the helper.

  3. Connect the bot to the helper (see Bot settings).

setup.sh does these steps:

  1. It checks the requirements and the flash drive shares.
  2. It downloads the helper files of the release and makes sure that each SHA-256 agrees with release.json of that release.
  3. It makes the helper directory, config.json, and api.key. It keeps a config.json and an api.key that already exist.
  4. It writes policy.json, which holds the SHA-256 of helper.pyz, and installs the helper files.
  5. It writes the startup hook and runs the Configuration check.
  6. It adds the hook to the User Scripts schedule with the frequency boot. Without this entry, the helper does not start.
  7. It starts the helper.
  8. For a bot that setup.sh installed, it writes SHAZZZBOT_HELPER_KEY and HELPER_SOCKET_DIR into the .env file 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.

config.json

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.

Bot settings

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:

  1. Put these lines in the .env file of the bot:

    SHAZZZBOT_HELPER_KEY=<the content of api.key>
    HELPER_SOCKET_DIR=/tmp/shazzzbot-helper/socket
  2. Make sure that HELPER_GID in .env is the same as socket_gid. Both defaults are 10001.

  3. Add this table to config.toml:

    [helper]
    socket = "/run/shazzzbot-helper/helper.sock"
    key_env = "SHAZZZBOT_HELPER_KEY"
  4. 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).

Startup hook options

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.

Configuration check

Run the startup hook with --check:

bash /boot/config/plugins/user.scripts/scripts/shazzzbot-helper/script --check

The 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.json has an unknown key, a wrong value, or a path outside the helper directory.
  • The SHA-256 of helper.pyz does not agree with policy.json.
  • The hook is not in the User Scripts schedule.
  • The flash drive has a writable share, and accept_flash_share is false.

Stop and start

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.

Logs

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.

Updates

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 --helper

setup.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:

  1. Put the new helper.pyz on an HTTPS server, and set update_url to its URL.

  2. Set update_sha256 to the SHA-256 of the file, and update_version to its version.

  3. 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>.

The bot without the helper

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.

Security model

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 root and mode 700. 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.pyz against the recorded values. It runs a copy of helper.pyz from 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 owner root and group socket_gid. The socket has mode 660. The helper also checks the user id of each connection against peer_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 the hello, tasks, and ups_shutdown actions, 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 root does not own, or that the group or other users can write. Each file can be at most 1 MiB, and one tasks read 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 root runs. Thus the helper does not start, and refuses each action, while the flash drive is writable over the network.
  • Pinned updates. --update downloads only over HTTPS, and only a file with the SHA-256 and the version in config.json. The version must be newer.

The helper never reboots or shuts down the server, and it never starts or stops the array.

Clone this wiki locally