Skip to content

Releases

v1.6.4

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 18 Nov 13:53
af69bfe

KTN Enclosure Manager 1.6.4

A security hardening release that follows up the 1.6.3 reviews. No data changes, and nobody is signed out: upgrade or roll back by changing the image tag. One behaviour change to check first: if your KTN_TRUENAS_URL is http:// or ws://, TrueNAS integration is off after the upgrade until you switch it to https:// (see Upgrading in the changelog).

  • TrueNAS API key: the key is no longer sent over http:// or ws://. TrueNAS documents that it revokes a key presented over insecure HTTP, so such a setup very likely had a revoked key already. The reason shows in the "TrueNAS unavailable" notice and on the Diagnostics tab; the drive map, telemetry and Identify keep working. KTN_TRUENAS_ALLOW_INSECURE=true restores the old behaviour.
  • Privileged helper: the root IDENT helper now starts Python isolated (python -I -S), so no .pth, sitecustomize or PYTHON* variable runs at its start. CI now starts the real helper in the built image.
  • Build: the image's Python dependencies install from wheels only. uvicorn[standard] is replaced by uvicorn with uvloop and httptools; PyYAML and watchfiles are gone.
  • Accounts and sign-in: new accounts start at a random session epoch, so deleting users.json and setting up again can no longer bring back sessions that a password change or "Sign out everywhere" had ended. Creating an account under an existing name is refused.
  • Diagnostics: /api/diagnostics shows KTN_TRUENAS_URL as scheme, host and port only, never a path, query or user:password@.
  • Fixes: upper-case URL schemes and URLs with surrounding whitespace are handled.

See CHANGELOG.md and SECURITY.md for details.

v1.6.3

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 17 Nov 01:00
c25b1fe

KTN Enclosure Manager 1.6.3

A security hardening release, based on an independent deep review. There is nothing to configure and no data changes: upgrade or roll back by changing the image tag. It also moves the runtime to Python 3.15.

  • Privileged helper: the root helper no longer follows a symlink or any other substitute planted at its lock file. On earlier versions, a web process that had already been compromised could use that to run code as root inside the container. The image's health check now also starts Python isolated, so a planted .pth or sitecustomize file is never executed.
  • Accounts and sign-in: account changes are now serialised and written atomically, so two first-run setups sent at once can no longer both "succeed", and concurrent changes no longer lose each other. A password change now also ends a session whose sign-in was still in progress when the change landed.
  • TrueNAS API key: a startup warning when KTN_TRUENAS_URL is http:// with an API key set. The key would be sent unencrypted, and TrueNAS documents that it revokes such keys. Use https://.
  • Alerts: new optional KTN_ALERT_DETAIL=minimal sends only the bay number and condition, with no serial, device or pool names. It is meant for webhooks on a third-party host such as a public ntfy.sh topic. The default, full, is unchanged.
  • Build: the image's Python libraries now come from a hash-pinned lock, so two builds of one release ship identical libraries, and CI tests that same set. A failed install can no longer produce a "successful" image.
  • Fixes: Identify on an enclosure whose SCSI generic device has gone away now returns a clean error instead of an internal error with endless retries. A flaky CI smoke check is fixed.

See CHANGELOG.md and SECURITY.md for details.

v1.6.2

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 31 Oct 17:19
8b7340c

KTN Enclosure Manager 1.6.2

A small maintenance release. Nothing to configure and no data changes. Upgrade or roll back by changing the image tag.

  • Health alerts: a mistyped alert URL is now a plain failed delivery with a one-line warning. Before, it could put a traceback in the log on every poll, skip other enclosures for that poll, and in one rare case write part of the URL, including a password, to the log. Fix the URL and the alert is delivered.
  • Accessibility: fixes for screen readers and keyboards. Bay tiles announce their contents and selection, the Change Password dialog keeps focus and closes on Escape, errors are announced, wide tables scroll from the keyboard, and focus rings are clearer. Automated checks find nothing serious or critical with no search active.
  • Light theme: three colours nudged darker to meet the 4.5:1 contrast standard.
  • Docs: a new table of HTTPS lockouts and fixes, plus clearer rules on alert delivery.
  • CI: the TLS smoke test no longer misreads a found log line as missing.
  • Known: text in tiles dimmed by a search stays low contrast.

See CHANGELOG.md for details.

v1.6.1

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 30 Oct 00:30
ffc50e5

Fixed

  • Dark theme: the bay numbers on the Drive map were near-black on the dark
    tiles
    (1.21:1). A tile is a <button>, buttons do not inherit colour, and
    the number was the one part of the tile with no colour of its own, so it
    took the browser's black. Tiles now use the theme's text colour (14.64:1 in
    dark). Light is unchanged to the eye: pure black became the theme's
    near-black #16202c, which all other text already uses.
  • Dark theme: the search placeholder used the browser's light-theme grey
    (3.45:1 on the dark field). It now has a dark value (6.49:1); light uses
    the same grey Chromium shows (#757575; Firefox and Safari may differ slightly).
  • Dark theme now declares color-scheme: dark, so the browser's own
    parts (the search field's clear button and, where the browser supports it, scrollbars) are
    drawn dark too, instead of in their light-theme colours.
  • A Playwright test measures the WCAG contrast of the bay numbers and of every
    visible text element on all three tabs and the change-password dialog,
    under Light, Dark and System with the OS preference emulated both ways.

v1.6.0

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 29 Oct 23:15
c25530f

Opt-in HTTPS. Nothing changes for an install that does not turn it on.

Added

  • KTN_TLS_ENABLED serves HTTPS directly from uvicorn - typically with
    the TrueNAS UI's own certificate, bound read-only into the container, so
    https://<that name>:8420 opens with no warning. Off by default. The
    entrypoint (root, holding only SETUID/SETGID) reads the root-only key
    through its owner bit and hands it to a uid-1000 writer on the /run/ktn
    tmpfs, so the served copy is 1000:1000 0600 and lives in RAM only; it
    refuses to start if that directory is not a tmpfs. Settings:
    KTN_TLS_CERTFILE, KTN_TLS_KEYFILE (absolute, distinct, required when
    on), KTN_TLS_RELOAD_CHECK_SECONDS (3600; 0 off; else at least 60) and
    KTN_TLS_RELOAD_SETTLE_SECONDS (60; at least 5). KTN_TLS_ENABLED accepts
    only 1/true/yes/on and 0/false/no/off/empty; the app and the entrypoint
    share that table and a test runs both over it.
  • Fail closed. With TLS on, a missing, unreadable, unparsable or
    mismatched pair exits with an ERROR: TLS ... line naming the paths (never
    their content) and the recovery. It never falls back to plain HTTP. The pair
    check (docker-tlscheck.py) retries for ten seconds, because TrueNAS writes
    the certificate and the key non-atomically. An expired certificate is served
    with a warning rather than refused.
  • Renewals are picked up automatically. The app hashes the mounted
    certificate hourly against the copy it serves - content, never mtime:
    TrueNAS rewrites its certificate files in place every day whether or not
    anything renewed - and on a change that is stable for the settle period and
    parses, audits tls.reload (fingerprints only) and shuts down gracefully;
    unless-stopped restarts it and the entrypoint installs the new pair.
  • /healthz reports tls (not_after, days_left, reload_pending)
    when TLS is on. It never turns non-200 for TLS state.
  • A container-level CI test (tls-smoke): the built image run with the
    TrueNAS-style hardening and a root 0400 key on a long-syntax bind -
    healthy over https, plain http refused, Secure cookie, key unreadable to
    uid 1000, an in-place renewal restarting it onto the new certificate, a
    mismatched key refusing to start with nothing listening, and plain HTTP
    unchanged when TLS is unset.

Changed

  • The image HEALTHCHECK is a script (docker-healthcheck.py) that
    follows KTN_PORT and KTN_TLS_ENABLED. The old inline command probed
    http://127.0.0.1:8420 whatever the port, and would have marked a TLS
    deployment unhealthy forever.

Fixed

  • truenas/fix-custom-app-metadata.py now refreshes the Web UI portal.
    For a custom app app.update never recomputes it, and the script preserved
    the stale value, so a changed x-portals (http to https, say) never reached
    the button. After the versions rename it now recomputes portals and notes
    with the middleware's own get_portals_and_app_notes, keeping the stored
    ones if that import is unavailable, and prints the resulting URLs only -
    never the rendered compose, which carries the API key. Its docstring and
    INSTALL-TRUENAS.md no longer claim app.update merges portals into the
    metadata file.
  • Pre-release review fixes. The app refuses to start when its
    KTN_TLS_ENABLED disagrees with what the entrypoint set up (a lowercase
    ktn_tls_enabled used to turn TLS "on" in the app while uvicorn served
    plain HTTP); the entrypoint now exports KTN_TLS_ACTIVE=1 only after
    building the TLS arguments. A failing audit write can no longer stop the
    renewal restart. The fix script refuses to rename onto an existing
    versions/<tag> (it used to nest the directory), keeps the stored portals
    and notes when x-portals fails validation, writes its YAML atomically at
    0600, takes its backup under umask 077, and prints the correct rollback
    (remove the dir, then extract).

Security

  • SECURITY.md names the trade plainly: the key served is the TrueNAS UI's
    own, so compromising the KTN web process would let an attacker impersonate
    the appliance UI by name on the LAN. A second certificate for the same name
    does not reduce that; only a different hostname would.
  • No HSTS is sent by KTN with TLS on either, and there is no http-to-https
    redirect (the port speaks TLS only; a same-port redirect is a possible later
    opt-in, KTN_TLS_HTTP_REDIRECT, not implemented). Update http://
    bookmarks and monitors to https://.

Fixed (also in 1.6.0)

  • A timed Identify's marker now goes out on time. The map learned of the
    server's clear only on the next 5 s bay poll, so the marker kept blinking
    for up to five seconds after the LED went dark (reported on Bay 15 after a
    30 s Identify). The map now puts the marker out at ident_expires_at and
    re-reads /bays once at that moment; a later expiry from the server cancels
    the pending stop, and "Until cleared" is unchanged. The detail panel still
    shows the server's state, so Clear stays available if the server's clear is
    being retried. /bays now carries generated_at (the server's clock), so
    the expiry is scheduled correctly when the browser's clock is skewed; the
    countdown uses the same correction.

v1.5.7

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 29 Oct 19:20
9d3875f

Security

  • The alert webhook URL no longer reaches the logs. For ntfy the topic, or
    an ?auth= token, is the credential. httpx logged HTTP Request: POST <full url> at INFO on every alert, and the app itself logged the URL when a
    webhook answered 4xx/5xx; KTN_LOG_LEVEL did not affect either. The httpx
    and httpcore loggers are now held at WARNING, the app logs scheme and host
    only, and the URL is scrubbed from delivery-error text. Tests drive a real
    httpx client and assert the secret is absent at DEBUG on the success, 3xx,
    4xx, 5xx and exception paths.

Fixed

  • A 3xx from the webhook is no longer counted as delivered. The client does
    not follow redirects, so a 301/308 (a moved topic, an http-to-https proxy)
    committed the alert as sent and never retried it. Only 2xx is delivery now.

v1.5.6

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 29 Oct 16:45
145a24a

Maintenance release.

Changed

  • Base image refreshed (python:3.14-slim digest a2b82f3), plus the
    frontend build toolchain and CI action bumps merged since 1.5.5.
  • The entrypoint waits up to 15 s, not 5 s, for the IDENT helper socket
    before warning that it did not appear.

Documentation

  • The fan question is recorded as closed: the firmware latches the fans high,
    and a 2026-10-26 power cycle did not release it (5300 RPM at +47 h).

v1.5.5 — correctness release

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 27 Aug 18:46

Correctness release. Every fix here is one root cause: the bay view composes
facts read on five different clocks — slots 5 s, TrueNAS 20 s, SES/AES 30 s,
SMART 120 s, disk identity live — and joining them without first establishing
that they describe the same disk, at the same moment, produces output that is
briefly but confidently wrong. v1.5.4 fixed that for the IDENT LED mapping;
this release fixes the rest of the family and stops the UI claiming a
freshness it does not have.

Fixed

  • A bay the app itself lit and then auto-cleared no longer reports as
    "external/unknown origin".
    The IDENT verdict composed a cached sysfs
    reading (up to poll_slots_seconds old) with the live record dict
    without ordering them, so in the window between a verified clear and the
    next slot poll a bay read as lit-with-no-owner — the app's own request,
    reported as an intruder's, while the LED was already physically out. Every
    offered duration is an exact multiple of the poll interval and the
    identify route re-phases that poll clock, so the expiry always landed
    beside a scheduled poll: the race was structural, not unlucky. Writes this
    app makes and verifies by hardware read-back are now stamped, and a
    reading older than our own last verified write is superseded by it. A
    genuinely external IDENT is still reported (§27) — only the single
    in-flight reading that straddles our own write is discarded.
  • A bay whose disk will not identify itself no longer wears the previous
    drive's identity.
    DiskInfoReader returned a silently empty identity when
    its sysfs reads failed, which is the one value the swap guard must read as
    "no conflict" (§20) — so the guard switched itself off during a re-probe or
    on a disk answering EIO, exactly when a same-name swap is most likely, and
    the departed drive's serial, pool membership and temperature alert were
    painted onto the bay. A read that failed is now distinguished from a disk
    that declares no identifiers. The identity is withheld; the failure
    signals are kept
    , because "we cannot tell which drive this is" says
    nothing about whether the bay is in trouble — and a permission regression
    makes every bay unreadable at once, which must not turn a failing shelf
    silent.
  • The identity-conflict drop now also covers the SAS address, which was
    stamped from the ≤30 s map after the drop ran — serving the departed
    drive's port address at the exact moment the app had proven the occupant
    changed, in the field an operator uses to cross-check against the shelf.
  • Health notifications no longer name the wrong drive. One transient join
    could send an urgent "Bay N failed" carrying another disk's serial, pool
    and temperature, persist it, then send a "recovered".
  • The audit log's serial is resolved live for the bay being acted on instead
    of being taken from the cached join, so the one record meant to be
    authoritative about which physical drive was touched cannot inherit a
    neighbour's identity. It is omitted rather than guessed when it cannot be
    resolved.
  • A failing discover() advanced no clock, so an unplugged shelf was retried
    every poll tick — each retry taking the cross-process enclosure lock the
    IDENT helper needs — while the error was never recorded anywhere.
  • poll_chassis stamped its cache as freshly read after reading nothing at
    all, so diagnostics reported a successful poll for telemetry of unbounded
    age.
  • The Identify route's post-write refresh is guarded: if it failed, the UI
    could show IDENT off with a disabled Clear button while the LED was lit
    and a timer was running, and a successful write could be reported to the
    caller as a 500.

Added

  • Fan telemetry, read-only. The chassis view now shows the SES speed code
    and the enclosure's own wording for it (Fan at third lowest speed), plus
    the requested-on flag, alongside the RPM it already displayed. The app was
    previously blind to these fields, which is what made the fan question hard
    to reason about: on this shelf the firmware runs the two banks at different
    speeds at identical temperatures, and now you can watch it do so. There is
    no fan control and none is planned — see the README.
  • The bays endpoint reports a slot-cache error alongside the existing
    freshness stamps, so a failing enclosure read is visible outside the
    diagnostics page.

Changed

  • The "updated" stamp no longer covers for four other clocks. One label
    described only the 5 s slot poll while the temperature under it could be
    120 s old, the ZFS state 20 s and the SAS address 30 s. The header now
    states the oldest contributing source and expands to a per-source
    breakdown; the detail panel stamps each section where that data actually
    renders. The UI also no longer asserts that bay state "remains accurate"
    when the enclosure read itself is failing.
  • The README's fan-control section no longer claims the firmware was
    observed refusing a speed request. The one command ever run
    (--set=speed_code=6) also carried RQST ON = 0, which SES-3 defines as
    turn the fan off, so it never tested a well-formed request. The section
    now leads with what is actually provable read-only — the shelf changed
    bank A from 5300 RPM to 2490 RPM with no host write to that subenclosure —
    and adds the structural closure: the Linux ses driver never enumerates
    cooling elements, so no sysfs fan path exists on any enclosure.

v1.5.4 — hardening release

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 27 Aug 05:52

Hardening release from a full adversarial pre-submission review (eight
independent lenses, every finding re-verified against the code). The one
user-visible behaviour change worth reading first: on enclosures where the
vendor's device slot numbering does not match the SES element index, Identify
now lights the correct bay
— previously it could light the wrong bay's LED
on such shelves (the KTN-STL3, where the two numberings coincide, was never
affected).

Fixed

  • Identify addresses bays through a device-slot→element-index map built
    from the enclosure's Additional Element Status page (already on the
    helper's read-only allow-list), cached per enclosure. The map is positional
    and guarded by page-integrity checks (misattribution tell-tales, element
    counts against the configuration page, printed-index offset consistency);
    a slot the page does not map unambiguously — or a page failing any check —
    is refused with a clear error instead of guessed at.
  • The SES configuration-page parser no longer mis-attributes a descriptor's
    element count and label when a type descriptor carries no text line (a
    normal sg_ses variant).
  • A seated drive that failed hard enough for the kernel to delete its block
    device now renders as failed, not as an empty bay: fault/Critical SES
    status is checked before the device-presence test.
  • Bay SAS addresses are joined on the AES device slot number instead of
    conflating element index with sysfs slot; when the mapping is unknown, no
    address is shown rather than possibly the wrong drive's.
  • A same-name disk swap can no longer wear the previous drive's ZFS/remote
    identity for a poll interval: remote records are dropped when serial/WWN
    disagree with the local identity.
  • Enclosure hardware I/O (discovery, slot reads — flock-guarded, up to 30 s)
    now runs in a worker thread instead of on the event loop, so a wedged
    shelf degrades the slot cache instead of stalling the whole HTTP surface
    including /healthz.
  • With the opt-in REST fallback enabled, transport and JSON-decode failures
    are contained as TrueNASError instead of escaping and starving the
    unrelated SES/SMART polls.
  • Health alerts are no longer lost to a transient webhook failure: a
    transition is committed only after the endpoint accepts it, and an
    undelivered one is retried until delivered or superseded, spaced per bay.
  • An expired Identify whose auto-clear hits a transient failure (helper
    restart, detached enclosure) is retried with bounded backoff instead of
    being dropped with the LED left lit; permanent failure is logged loudly.
  • Login rate limiting is thread-safe under concurrent requests, and a
    rate-limited login is answered 429 (matching change-password) instead
    of 401.
  • The chassis view maps SES statuses onto the full health scale —
    Critical/Unrecoverable show as failed, not flattened to a warning badge —
    and a failed sign-out now surfaces on the screen the user lands on (the
    login-screen notice — or the error banner when authentication is
    disabled) instead of being silently swallowed.

Added

  • Shelves that report drive bays as plain Device slot elements (SES type
    0x01) are now supported alongside Array device slot (0x17) for discovery,
    Identify and SAS addresses.
  • KTN_ALLOWED_HOSTS: optional Host-header allow-list closing DNS rebinding
    when running with authentication disabled (default: allow all, unchanged).
  • KTN_FORWARDED_ALLOW_IPS: trust X-Forwarded-Proto from a named reverse
    proxy so the session cookie's Secure flag survives TLS termination
    (default unchanged: localhost only).
  • Root helper: per-connection socket timeout (an idle client no longer pins
    a root-process thread), and the post-bind chown/chmod verifies via
    lstat that the path is a non-symlink socket before touching it.
  • Test coverage for the previously untested security core: the helper's
    request dispatcher, the production Identify write path (helper socket +
    SES command), and expired/tampered/unsigned session cookies — plus
    negative-path auth tests and new E2E flows.

Changed

  • The image applies Debian security point-releases at build time. Both
    base images stay digest-pinned, but Docker Hub rebuilds slim images on its
    own schedule, so a pinned digest can carry an already-fixed CVE for days —
    this release ships with the openssl fix for CVE-2026-14456, which the
    newest published digest still lacked.
  • Release workflows: single tag trigger with a concurrency group, latest
    only for the highest semver tag, third-party actions pinned to commit
    SHAs, and the arm64 image now passes the Trivy gate before publish.
  • Documentation truth pass: INSTALL-TRUENAS.md, SECURITY.md, ARCHITECTURE.md
    and the staged catalog package no longer carry pre-1.5.2 claims (writable
    /sys, AppArmor relaxation, the retracted "SG_IO counts as a write"
    rationale, the removed setgid-bit mechanism); SECURITY.md now documents
    six allow-listed read methods and the system.version fallback.

v1.5.3 — the vector icon ships in-image

Choose a tag to compare

@MechanicalCoderX MechanicalCoderX released this 20 Aug 15:09
875cafd

Polish release ahead of wider publicity; no behaviour changes.

  • The in-app favicon now ships at 256px (was 64) and the vector icon.svg is served by the app itself — both introduced in the repo alongside 1.5.2, delivered to installs here.
  • Release notes also collect the between-tags repo work: full docs accuracy audit (with a CI guard keeping the README version-neutral), screenshots regenerated to show the real 15-bay shelf (the fixture's synthetic SES-99 test slot no longer appears in user-facing images), Identify demo GIF, issue form templates + Discussions, and the measured per-bank fan-speed correction.