mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-04 06:15:09 +00:00
ChuckandClaude Opus 5.5
3967a6cffc
* docs: add ARCHITECTURE and PERMISSIONS guides ARCHITECTURE.md maps the processes, the state the display and web services share through the cache, the display loop, the plugin system, the web UI and the update path, with links into the code and a where-to-start table. PERMISSIONS.md lists who owns what after install, both sudoers files (and why iptables is not granted), the polkit rule, and which scripts/fix_perms script to run as which user. Both are linked from the docs index, along with the MQTT bridge README and src/common/README.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: correct stale setup, service and troubleshooting claims - README: quick actions run systemctl on ledmatrix.service (run.py), not display_controller.py; use_short_date_format has no effect; the installer uses system pip with --break-system-packages, not a venv. - CONFIG_DEBUGGING: LEDMATRIX_DEBUG must be "true"; logs are in journald. - GETTING_STARTED, WEB_INTERFACE_GUIDE, TROUBLESHOOTING: enabling a plugin, plugin settings, brightness and Vegas settings apply without a restart; matrix hardware settings still need one. - TROUBLESHOOTING: install dependencies with sudo so the root service sees them; point permission problems at PERMISSIONS.md instead of a project-wide chown. - ADVANCED_FEATURES: real BackgroundDataService stats keys; Vegas hooks return VegasDisplayMode and None falls back to capture; cache files are 0660; fix_web_permissions.sh runs as the web user and does not touch sudoers. - STARLARK_APPS_GUIDE: only the linux-arm64 pixlet binary is downloaded. - HOW_TO_RUN_TESTS: test class examples that exist. - CLAUDE.md: PluginStoreManager, plugin_dirs.py, monorepo installs via the Trees API with ZIP fallback, requirements.txt is optional. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: mark deprecated plugin APIs and state manifest fields once Methods @deprecated("3.7.0") (the set pinned in test_deprecation.py) were shown as current API in the quick reference, API reference, advanced guide, development guide and FONT_MANAGER. Each is now marked deprecated with its replacement. FONT_MANAGER is rewritten around the current API; the override editor is gone and override methods are deprecated. Required manifest fields were stated three different ways. The API reference now has one section: the 7 schema-required fields, the 4 the store refuses without, class_name for the loader, and the 8 to set. The other guides link to it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: document every src/common module and every widget - src/common/README.md covered 7 of 17 modules. It now has a table of all of them (purpose, whether plugins import it, release to floor on), a short entry each, and logging advice that matches the code. - SPORTS_UNIFICATION listed two shared modules and called sports_helpers the first; it now lists all six. - The widgets README lists all 28 registered widgets plus the support files, and absorbs the parts that only docs/widget-guide.md had (x-options.labels, x-advanced, x-display hidden, plugin-file-manager). docs/widget-guide.md is now a pointer to it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(security): fix_web_permissions.sh re-hardens the root sudo helpers The script chowns the whole project to the web user. That included scripts/fix_perms/safe_plugin_rm.sh and safe_pip_install.sh -- the two helpers /etc/sudoers.d/ledmatrix_web lets the web user run as root -- so running it turned both into a root shell for whoever can edit them. It also re-grouped config_secrets.json away from ledmatrix. After the chown it now does what first_time_install.sh's Steps 11 and 11.1 do: helpers back to root:root 755, and config_secrets.json back to the web unit's User=:ledmatrix 640. Each step is non-fatal and prints the manual command if it fails. Also fixes what the script and its docs claimed: it never configured sudoers, its closing hint pointed at ./configure_web_sudo.sh (wrong path), and the README and ADVANCED_FEATURES.md said to run it with sudo, which it refuses. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(security): validate and harden every sudoers drop-in the scripts write configure_wifi_permissions.sh copied its rules into /etc/sudoers.d/ledmatrix_wifi without `visudo -c`. A malformed drop-in makes sudo refuse every command for every user, which on a headless Pi leaves no way back in. It now checks first and leaves the installed file alone when the rules do not parse, as the other two writers do. (It already used mktemp, so that part of the review did not apply.) It also grants the two literal commands wifi_manager.py runs for NetworkManager's shared-mode dnsmasq drop-in -- `cp /tmp/ledmatrix-nm-dnsmasq.conf .../dnsmasq-shared.d/ledmatrix-captive.conf` and `rm -f` of that file. The directory's mkdir was granted, the file was not. Both are pinned in test_sudo_allowlist_covers_calls.py. configure_web_sudo.sh wrote its rules to /tmp/ledmatrix_web_sudoers_$$, a predictable name in a world-writable directory; it now uses mktemp with an EXIT trap, as first_time_install.sh does. It sets mode 440 on the installed file instead of leaving the temp file's mode, and finds visudo in /usr/sbin when that is not on the user's PATH, which skipped the check silently. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(install): escape the project path in the DNS-fix and MQTT unit renderers install_dns_fix.sh and install_mqtt_bridge.sh substituted __PROJECT_ROOT_DIR__ with the raw path, while the other three renderers go through sed_escape_replacement from lib_systemd_render.sh. A checkout under a path containing `&`, `\` or `|` rendered a corrupted unit from these two only. Both now source the helper and use it, and a test checks that every placeholder substitution in scripts/install uses an escaped value. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(install): stop the installer scripts reporting things that are not true - first_time_install.sh printed "Password: ledmatrix123" for the setup access point. wifi_manager creates it as an open network ("No password" on the panel), so it now says so. - Step 10.1 printed "✓ WiFi management permissions configured" straight after its own failure message; install_wifi_monitor.sh printed "✓ Package installation completed" after a failed apt install. The tick now only follows success. - Step 7 printed "Web dependencies already installed ... in Step 5" in the one branch that runs because Step 5 did not install them, then created .web_deps_installed on that basis. It now warns and leaves the marker off so the next run retries, as the comment below it intends. - check_system_compatibility.sh called Debian 12 Bookworm "full compatibility confirmed" while first_time_install.sh refuses anything but Debian 13. Bookworm, older Debian and non-Debian systems are now errors. Its counters used ((X++)), which under `set -e` exits the script at the first warning or error (the expression is 0), so the check never reached its summary on any system with one. - configure_web_sudo.sh and configure_wifi_permissions.sh finished by testing `sudo -n test -f ...` and `sudo -n nmcli device status`, neither of which is granted, so they always reported a failure. They now ask `sudo -n -l` about commands the new rules do grant, which checks the rule without running anything. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(install): print the completion summary before rebooting With -y -- and so for every one-shot `curl | bash` install, which always passes -y -- first_time_install.sh ran `reboot` about 180 lines before its "Installation Complete / Web UI Access" summary. reboot returns at once, so the summary printed while the Pi was going down and the SSH session usually dropped before the web UI address could be read. The reboot block moves, unchanged, to the very end of the script. The interactive prompt now also follows the summary. Because the summary now runs before the -y reboot, its one command that could fail under `set -Eeuo pipefail` (the SSID lookup, when nmcli reports a connected device but no active network line) gets `|| true`; a missing SSID was already handled as "SSID unknown". one-shot-install.sh prints its "Next steps" after the installer returns, by which time the reboot is under way, so it now says so, and README's Quick Install mentions the automatic reboot. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(scripts): correct wrong comments and messages, drop dead code No behaviour change except the output text noted below. - 2775 is setgid, not the sticky bit (first_time_install.sh Step 3.1, fix_plugin_permissions.sh), and root needs no "PWM hardware access" to plugin files. - The 777 comments in first_time_install.sh Step 3's fallback and fix_assets_permissions.sh said root needs it to write. Root ignores mode bits; the comments now say what 777 actually opens. The 777 itself is unchanged. - apt_remove ends in `|| true`, so Step 12's "Some packages could not be removed" branch could never run; it is gone and the helper stays non-fatal. - detect_web_service_user's comment named Step 8 for the web unit (install_service.sh installs it in Step 7.5) and now says which branch actually runs. - Step 5 described an "already installed" check that does not exist; the ACTUAL_USER comment described the re-exec backwards. - on_error printed a literal "\n" before "Common fixes:". - Dead code: one-shot-install.sh's uncalled fix_tmp_permissions, LEDMATRIX_ELEVATED=1 (never read) on the sudo re-exec, and configure_web_sudo.sh's unused PYTHON_PATH, which also made a missing python3 fatal for rules that never mention it. - start_display.sh / stop_display.sh said "for user: <you>"; the service runs as root. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(fix_perms): fix_cache_permissions.sh uses setup_cache.sh's model There were two models for /var/cache/ledmatrix. setup_cache.sh (the installer's Step 2) and install_web_service.sh share it through the ledmatrix group: root:ledmatrix, 2775, files 660, which is also what DiskCache relies on to give files the directory's group. fix_cache_permissions.sh instead made it 777 and re-grouped it to the invoking user's group, undoing that. It now runs setup_cache.sh for /var/cache/ledmatrix and keeps its own handling of ~/.ledmatrix_cache. Dropped: /var/cache/ledmatrix/ placeholder_logos (nothing reads it) and the checks against the `daemon` user (no service runs as daemon). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * ci: pin actions/checkout in the Claude workflows, drop template comments claude.yml and claude-code-review.yml used actions/checkout@v4 while test.yml and release-version-check.yml pin the v4.2.2 commit SHA; they now pin the same SHA. The commented-out starter-template settings (prompt, claude_args, paths, author filter) are removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(scripts): index every script and list removal candidates New scripts/README.md gives one line per top-level script and scripts directory, marked keep, dev-only or diagnostic, and lists the eight scripts nothing in the repo refers to as candidates for removal (kept for now). The install, utils and dev READMEs now list the files they were missing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test: tighten two checks that mutation testing showed were too loose - The wifi sudoers check matched `visudo -c -f "$TEMP_SUDOERS"` in the error report too, so replacing the check with `if false` still passed. It now requires the command as the condition. - The summary test never had the setup access point up, so reinstating the bogus "Password: ledmatrix123" line went unnoticed. A case with hostapd active now checks the AP is described as open. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(permissions): describe the repaired fix_perms scripts and new WiFi grants Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(changelog): docs-scripts Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
8.1 KiB
8.1 KiB
Permissions
Who owns what on an installed system, which privileged commands the web
interface may run, and how to repair ownership when it goes wrong. The
installer, first_time_install.sh, sets all of
this up; this page describes the result.
Users and groups
| Account | Used by | Why |
|---|---|---|
root |
ledmatrix.service (the display) |
The LED matrix library needs direct GPIO access |
The installing user (e.g. ledpi) |
ledmatrix-web.service, ledmatrix-update-verify.service |
A web server should not run as root |
ledmatrix group |
shared files | Members: the installing user, root, and daemon if it exists. Created by setup_cache.sh and the installer |
The installer also adds the web user to systemd-journal and adm so the
Logs tab can read the journal. Group changes apply after the user logs
in again (services pick them up on restart).
Files and directories
| Path | Owner | Mode | Notes |
|---|---|---|---|
| Project directory | web user | dirs 755, files 644, *.sh 755 |
Set in the installer's "Normalize project file permissions" step |
config/ |
web user | 2775 |
|
config/config.json |
web user | 644 |
Written by the web interface |
config/config_secrets.json |
web user : ledmatrix |
640 |
Owned by the web user because the web interface writes it; root reads it regardless of mode |
plugin-repos/, plugins/ |
web user | dirs 2775, files 664 |
The web interface installs and removes plugins |
assets/ |
web user | dirs 755, files 644 |
Root writes downloaded logos regardless |
/var/cache/ledmatrix/ |
root:ledmatrix |
2775 (setgid) |
Shared cache: see below |
| Cache files | creator : ledmatrix |
660 |
|
scripts/fix_perms/safe_plugin_rm.sh, safe_pip_install.sh |
root:root |
755 |
Run as root through sudo, so the web user must not be able to edit them |
/etc/sudoers.d/ledmatrix_web, ledmatrix_wifi |
root |
440 |
What keeps it that way at runtime:
- Config files. Saves go through
src/config_manager_atomic.py, which appliesget_config_file_mode()(640for secrets,644otherwise) and, when running as root, moves the file's group to the project directory's group (ensure_shared_group_ownership()insrc/common/permission_utils.py). - Cache files.
src/cache/disk_cache.pysets every file it writes to0660and gives it the cache directory's group, without relying on the setgid bit. So a file root writes stays readable by the web user. - Plugin directories.
run.pysetssys.dont_write_bytecode, because root-owned__pycache__directories inside a plugin stop the web user updating or removing it.
ledmatrix-web.service deliberately has no CacheDirectory=: systemd would
re-own /var/cache/ledmatrix to the web user and its primary group, and the
web interface could no longer read what the display writes (see the comment
in systemd/ledmatrix-web.service).
If /var/cache/ledmatrix is not usable, CacheManager falls back to
~/.ledmatrix_cache, /opt/ledmatrix/cache or a temp directory
(src/cache_manager.py). The two services then
may not share a cache, and the web UI shows stale or empty display status,
on-demand state and plugin health. Fix the directory rather than living
with the fallback.
sudo rules
/etc/sudoers.d/ledmatrix_web
Generated by web_sudoers_rules() in
scripts/install/lib_sudoers.sh, the
only place these rules are defined. Installed by the installer and by
configure_web_sudo.sh, both of
which check them with visudo -c first. The web user may run, without a
password:
reboot,poweroffsystemctl start|stop|restart|enable|disable|status ledmatrix.service,systemctl is-active ledmatrix[.service]systemctl start|stop|restart ledmatrix-web.servicebash <project>/scripts/fix_perms/safe_plugin_rm.sh *— removes a directory only if it resolves to a child ofplugin-repos/orplugins/bash <project>/scripts/fix_perms/safe_pip_install.sh *— installs arequirements.txtonly if it is the project's own or one underplugin-repos/orplugins/, so the root display service can import the packagesjournalctl -u ledmatrix.service *,-u ledmatrix *,-t ledmatrix *, taggedNOEXEC: journalctl opens a pager on a terminal, and a shell escape from that pager would be a root shell
/etc/sudoers.d/ledmatrix_wifi
Written by
scripts/install/configure_wifi_permissions.sh
(run as the web user; the installer calls it). It refuses to grant a binary
that is not root-owned or is group/world-writable. The rules cover:
nmcli device wifi connect|disconnect *,nmcli device connect|disconnect *,nmcli radio wifi on|offsystemctl start|stop|restart hostapd,... dnsmasq,systemctl restart NetworkManagersysctl -w net.ipv4.ip_forward=0|1nft add|delete table ip ledmatrixrfkill unblock wifimkdir -p /etc/NetworkManager/dnsmasq-shared.dcpof/tmp/hostapd.confand/tmp/dnsmasq.confto their fixed destinations, andrm -f /etc/dnsmasq.d/ledmatrix-captive.confcp /tmp/ledmatrix-nm-dnsmasq.confto/etc/NetworkManager/dnsmasq-shared.d/ledmatrix-captive.conf, andrm -fof that file
iptables is deliberately not granted. The captive portal's rules are
built from the interface name and port, so a rule covering them would need a
trailing wildcard, and iptables --modprobe=<path> runs <path> as root: a
wildcard grant is a root shell for the web user. Doing it safely needs a
wrapper script that builds the rules itself, like safe_plugin_rm.sh. On a
stock Raspberry Pi OS image the default user's blanket NOPASSWD rule
(/etc/sudoers.d/010_pi-nopasswd) hides this gap.
polkit
The same script installs /etc/polkit-1/rules.d/10-ledmatrix-wifi.rules,
which lets the web user perform any org.freedesktop.NetworkManager.*
action without authentication.
Repair scripts
In scripts/fix_perms/. Run them from the project
directory.
| Script | Run as | What it does | Notes |
|---|---|---|---|
fix_plugin_permissions.sh |
sudo |
plugins/ and plugin-repos/ to root:<user>, dirs 2775, files 664; makes a 700 home directory 755 so root can traverse it |
Safe. Group-writable, so the web user keeps write access |
fix_assets_permissions.sh |
sudo |
assets/ to <user>:<group>, mode 777 recursively |
Works, but looser than the installer's 755/644 |
fix_cache_permissions.sh |
sudo |
Runs setup_cache.sh for /var/cache/ledmatrix (root:ledmatrix, 2775, files 660), then makes ~/.ledmatrix_cache (the fallback cache) <user>:<group> mode 777 |
Safe. The ~/.ledmatrix_cache mode is still 777 |
fix_web_permissions.sh |
the web user, without sudo |
Resets project file ownership for the web user (it calls sudo itself), then makes safe_plugin_rm.sh and safe_pip_install.sh root:root 755 again and restores config_secrets.json to its owner, group ledmatrix, mode 640 |
Refuses to run as root. It does not write sudoers rules |
safe_plugin_rm.sh, safe_pip_install.sh |
— | Called by the web interface through sudo | Not for manual use |
To reinstall the sudoers rules, run
./scripts/install/configure_web_sudo.sh (web rules) or
./scripts/install/configure_wifi_permissions.sh (WiFi rules and polkit) as
the web user, not with sudo.
After any of these, restart both services:
sudo systemctl restart ledmatrix.service ledmatrix-web.service
Checking
ls -ld /var/cache/ledmatrix # drwxrwsr-x root ledmatrix
stat -c '%U:%G %a %n' config/config.json config/config_secrets.json
id # web user should list ledmatrix
sudo -l # lists the NOPASSWD rules