kioskOS/os
Watch
1
0
Fork
You've already forked os
 0
Code Issues Pull requests Projects Releases 4 Packages Wiki Activity Actions
4 releases 4 tags
  • v2.1.0 b9a5f8ada6

    v2.1.0 Stable

    kaisa released this 2026-08-04 23:17:31 +00:00 | 0 commits to main since this release

    Highlights

    • Remote shell jobs — administrators can queue arbitrary shell commands
      (or one-click presets) against a kiosk from the admin UI; the device runs
      them as root and reports back the exit code and output. Off by default,
      per device.
    • Touchscreens now follow screen rotation — touch input is re-mapped
      with xinput map-to-output after every rotation, at cold boot, and when
      a USB touchscreen reconnects.
    • Agent startup crash fixed — the 2.0.0 agent could crash on launch
      with "'http' is not a package" due to a sys.path shadowing bug.
    • Image fixes for real-world hardware — NTP time sync for devices with
      dead RTC batteries, and AMD GPU firmware so rotation works on AMD APUs.

    No breaking changes. 2.0.0 agents keep working against a 2.1.0 server —
    they simply ignore the new jobs field in check-in responses. Remote shell
    jobs require a 2.1.0 agent and an explicit per-kiosk opt-in.

    Upgrading already-deployed kiosks: the agent package now depends on
    xinput and x11-xserver-utils, so apt install --only-upgrade kioskos-agent pulls the touch-mapping tools onto devices imaged before they
    were in the ISO. For the image-level fixes (time sync, AMD firmware) run the
    one-shot scripts/hotfix-amd-firmware-timesync.sh
    on each device — idempotent, and it reboots only when the GPU fix requires it.

    Control (Django control server)

    Remote shell jobs

    • New KioskJob model and full job lifecycle: pending → running → succeeded / failed / timed_out, plus cancelled (before delivery),
      expired (not delivered within the 1-hour TTL — a device unplugged for a
      fortnight must not come back and run last month's upgrade), and lost
      (delivered but no result within timeout + grace, e.g. the command rebooted
      the device).
    • Jobs are pulled, not pushed: the server holds them until the device's
      next check-in, so the feature works for kiosks behind NAT on customer
      networks. Delivery latency is bounded by the check-in interval.
    • Each job is handed out exactly once — rows are claimed with a
      compare-and-swap on status, so two racing check-ins cannot both be told
      to run the same command. Up to 5 jobs are delivered per check-in.
    • Named presets for routine fleet operations: update all packages,
      upgrade the agent, restart the agent, reboot, report disk usage, tail the
      agent journal. reboot and restart_agent detach and delay so the job
      can report success before taking the agent down with it.
    • Off by default: a new per-kiosk shell_enabled flag gates both
      queueing and delivery. The agent runs jobs as root, so the capability is
      granted deliberately per device, never fleet-wide.
    • Kiosk detail page grew a shell job panel: queue a preset or a custom
      command, watch status, and read captured stdout/stderr; jobs not yet
      delivered can be cancelled.
    • Expired/lost transitions are applied lazily on the check-in and job-list
      paths — the deployment has no worker process, and check-in is the only
      clock the server can rely on.
    • Every queue, delivery, and completion is recorded as a KioskEvent
      (new job event type), so the audit trail shows what ran where, who
      asked for it, and how it ended. The created_by admin is kept even if
      the account is later deleted.
    • Output is truncated server-side at 64 kB per stream (keeping the tail,
      where failures explain themselves) as a backstop behind the agent's own
      32 kB cap.
    • Test suite extended with full coverage of queueing, claiming, result
      reporting, cancellation, expiry/lost reaping, and permission boundaries.

    KioskOS Agent (kioskos-agent 2.1.0)

    Remote shell jobs

    • New agent/shell.py job runner: jobs execute on a dedicated worker
      thread, one at a time — a ten-minute package upgrade must not freeze the
      check-in loop, which is also the dead-browser watchdog; serial execution
      keeps two apt runs from fighting over the dpkg lock.
    • Commands run via bash -c in their own process group (a timeout
      SIGTERMs, then SIGKILLs the whole tree, not just the shell), with stdin
      closed (anything that prompts fails fast instead of hanging) and a fixed
      environment (DEBIAN_FRONTEND=noninteractive, sane PATH,
      LC_ALL=C.UTF-8).
    • Captured output is capped at 32 kB per stream, keeping the tail.
    • Results that cannot be posted (device offline) are held and retried
      on later check-ins, bounded to the 50 most recent.
    • Device-side veto: a new shell_enabled key in
      /etc/kioskos/config.json (default true) lets an operator mark a
      device as never accepting remote commands regardless of what the control
      server says; refused jobs report exit code 126 so the admin sees a reason
      instead of a job that silently never finishes.
    • On shutdown the runner stops taking new jobs but lets a running job
      finish — interrupting an upgrade mid-dpkg would be worse than losing
      the result. New test module tests/test_shell.py.

    Touchscreen rotation (2.0.1)

    • Fixed touch input staying in the panel's native orientation after screen
      rotation: set_orientation() now re-maps every calibratable touch device
      onto the rotated output via xinput map-to-output. Touch devices are
      identified by the libinput Calibration Matrix property, so mice and
      other relative pointers are never affected.
    • The agent package now depends on xinput and x11-xserver-utils — the
      tools display.py actually shells out to — so upgrading the package
      pulls them onto devices imaged before they were added to the ISO.

    Startup crash & self-update fixes (2.0.2)

    • Fixed an agent crash on startup (No module named 'http.client'; 'http' is not a package): the service ran with
      WorkingDirectory=/opt/kioskos/agent, and python -m puts the working
      directory first on sys.path, so the agent's own http.py shadowed the
      stdlib http package that requests imports. The service now runs from
      /opt/kioskos and sets PYTHONSAFEPATH=1 so the working directory can
      never leak onto sys.path again.
    • Self-update now refreshes all apt sources instead of only the kioskos
      repo — dependencies introduced by a new agent version come from the
      Debian repos, which ISO-imaged devices have no cached lists for — and
      tolerates a skewed clock during the refresh (dead RTC batteries make apt
      reject Release files as "not valid yet").

    Multi-display & cold-boot touch mapping (2.0.3)

    • Touch devices are no longer all mapped to the primary output: one display
      gets every touch device (the common kiosk); equal counts of touch devices
      and displays are paired deterministically (device IDs ascending, outputs
      left-to-right); a count mismatch falls back to the primary output with a
      warning. Mirrored layouts share one rectangle, so any pairing is correct
      there.
    • Fixed touch mapping not applied on cold boot: the agent rotates the
      screen as soon as the X socket exists — before Xorg has enumerated input
      devices via udev — so there was nothing to map yet. A startup thread now
      polls for touch devices and maps them as soon as they appear, and the
      check-in loop re-applies mappings every cycle, so a USB touchscreen that
      reconnects mid-session heals within one interval instead of staying on
      the identity matrix.

    KioskOS OS (image & build system)

    • systemd-timesyncd added to the image and enabled at provision time:
      kiosks often have dead RTC batteries, and a skewed clock breaks both apt
      ("Release file not valid yet") and TLS to the control server.
    • firmware-amd-graphics added: without it the amdgpu driver cannot
      load on AMD APUs, X falls back to the EFI framebuffer, and screen
      rotation is unavailable.
    • xinput added for the agent's touch-input remapping.
    • New one-shot hotfix script
      (kiosk/scripts/hotfix-amd-firmware-timesync.sh) brings already-deployed
      devices in line with the image fixes above — idempotent, fleet-friendly
      over SSH, and reboots only when the GPU fix requires it (--no-reboot to
      suppress).
    • Calamares installer branding now reports the real product version
      (2.1.0 — it had still claimed 1.0.0).
    • ARCHITECTURE.md documents the full remote shell job design (lifecycle,
      the two-switch permission model, endpoints, and device-side execution).

    Protocol (agent ↔ server API v1)

    New in check-in responses

    • jobs: an array of {id, command, timeout, preset} shell jobs
      claimed by this check-in. Each job appears in exactly one response.
      Absent/empty for kiosks without shell_enabled; older agents ignore it.

    New endpoints

    Endpoint Auth Purpose
    POST /api/v1/jobs/{id}/result/ device token Device reports exit_code, stdout, stderr, duration_seconds, timed_out.
    POST /api/v1/kiosks/{uid}/jobs/ admin session Queue a job (command or preset, plus optional timeout, expires_in).
    GET /api/v1/kiosks/{uid}/jobs/ admin session Job history for a device, filterable by status.
    GET /api/v1/jobs/{id}/ admin session One job with its captured output.
    POST /api/v1/jobs/{id}/cancel/ admin session Cancel an undelivered job (409 once it has been handed out).
    GET /api/v1/job-presets/ admin session Named commands offered by the UI.

    Security model

    • The result endpoint is scoped to the reporting device — a kiosk can
      only close out a job that was handed to it, so a leaked device token
      cannot forge results for the rest of the fleet.
    • Queueing requires an admin session; a device token is refused, so a
      compromised kiosk cannot queue work for itself.
    • Two switches, both required: the server-side per-kiosk shell_enabled
      flag (default off, checked at queue time and delivery time) and the
      device-side shell_enabled config key (default on, the operator's veto).
    Downloads