Repository navigation
Releases
v1.6.4
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://orws://. 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=truerestores the old behaviour. - Privileged helper: the root IDENT helper now starts Python isolated (
python -I -S), so no.pth,sitecustomizeorPYTHON*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 byuvicornwithuvloopandhttptools; PyYAML and watchfiles are gone. - Accounts and sign-in: new accounts start at a random session epoch, so deleting
users.jsonand 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/diagnosticsshowsKTN_TRUENAS_URLas scheme, host and port only, never a path, query oruser:password@. - Fixes: upper-case URL schemes and URLs with surrounding whitespace are handled.
See CHANGELOG.md and SECURITY.md for details.
v1.6.3
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
.pthorsitecustomizefile 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_URLishttp://with an API key set. The key would be sent unencrypted, and TrueNAS documents that it revokes such keys. Usehttps://. - Alerts: new optional
KTN_ALERT_DETAIL=minimalsends 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
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
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
Opt-in HTTPS. Nothing changes for an install that does not turn it on.
Added
KTN_TLS_ENABLEDserves HTTPS directly from uvicorn - typically with
the TrueNAS UI's own certificate, bound read-only into the container, so
https://<that name>:8420opens with no warning. Off by default. The
entrypoint (root, holding onlySETUID/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 is1000:1000 0600and 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;0off; else at least 60) and
KTN_TLS_RELOAD_SETTLE_SECONDS(60; at least 5).KTN_TLS_ENABLEDaccepts
only1/true/yes/onand0/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 anERROR: 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, auditstls.reload(fingerprints only) and shuts down gracefully;
unless-stoppedrestarts it and the entrypoint installs the new pair. /healthzreportstls(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 root0400key on a long-syntax bind -
healthy over https, plain http refused,Securecookie, 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
followsKTN_PORTandKTN_TLS_ENABLED. The old inline command probed
http://127.0.0.1:8420whatever the port, and would have marked a TLS
deployment unhealthy forever.
Fixed
truenas/fix-custom-app-metadata.pynow refreshes the Web UI portal.
For a custom appapp.updatenever recomputes it, and the script preserved
the stale value, so a changedx-portals(http to https, say) never reached
the button. After the versions rename it now recomputes portals and notes
with the middleware's ownget_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 claimapp.updatemerges portals into the
metadata file.- Pre-release review fixes. The app refuses to start when its
KTN_TLS_ENABLEDdisagrees with what the entrypoint set up (a lowercase
ktn_tls_enabledused to turn TLS "on" in the app while uvicorn served
plain HTTP); the entrypoint now exportsKTN_TLS_ACTIVE=1only 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 whenx-portalsfails validation, writes its YAML atomically at
0600, takes its backup under umask077, 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). Updatehttp://
bookmarks and monitors tohttps://.
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 atident_expires_atand
re-reads/baysonce 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./baysnow carriesgenerated_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
Security
- The alert webhook URL no longer reaches the logs. For ntfy the topic, or
an?auth=token, is the credential. httpx loggedHTTP Request: POST <full url>at INFO on every alert, and the app itself logged the URL when a
webhook answered 4xx/5xx;KTN_LOG_LEVELdid not affect either. Thehttpx
andhttpcoreloggers 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
Maintenance release.
Changed
- Base image refreshed (
python:3.14-slimdigesta2b82f3), 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
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 topoll_slots_secondsold) 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.DiskInfoReaderreturned 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_chassisstamped 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 carriedRQST 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 Linuxsesdriver never enumerates
cooling elements, so no sysfs fan path exists on any enclosure.
v1.5.4 — hardening release
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 asTrueNASErrorinstead 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 answered429(matching change-password) instead
of401. - 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: trustX-Forwarded-Protofrom a named reverse
proxy so the session cookie'sSecureflag 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
lstatthat 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 thesystem.versionfallback.
v1.5.3 — the vector icon ships in-image
Polish release ahead of wider publicity; no behaviour changes.
- The in-app favicon now ships at 256px (was 64) and the vector
icon.svgis 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.