Skip to content

feat: mount the Home Assistant /ssl directory read-only - #873

Merged
Koenkk merged 2 commits into
zigbee2mqtt:masterfrom
cmatte:map-ssl-directory
Sep 22, 2026
Merged

Koenkk merged 2 commits into
zigbee2mqtt:masterfrom
cmatte:map-ssl-directory

Conversation

@cmatte

@cmatte cmatte commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

Closes #835.

The addon maps share, homeassistant_config and addon_config, but not the standard Home Assistant /ssl directory. Certificates managed by addons such as Let's Encrypt live there, so an MQTT TLS configuration that points at them fails at startup:

error: z2m: MQTT failed to connect, exiting...
(ENOENT: no such file or directory, open '/ssl/privkey.pem')

Copying the certificate and key into a mapped directory works, but has to be repeated on every renewal — which defeats the point of automated renewal. A symlink from the mapped config directory into /ssl is not followed.

Change

Map ssl alongside the existing mappings, read-only:

{
  "type": "ssl",
  "read_only": true
}

Read-only is sufficient — the addon only needs to read the certificate and key, and renewal is performed by whichever addon manages them. Because the directory is mounted rather than copied, renewals are picked up with no further action.

Users can then reference the certificates directly:

mqtt:
  server: mqtts://core-mosquitto:8883
  key: /ssl/privkey.pem
  cert: /ssl/fullchain.pem

Scope

  • Applied to both zigbee2mqtt and zigbee2mqtt-edge.
  • zigbee2mqtt-proxy is unchanged — it does not connect to MQTT.
  • No version bump, following the /addon_config mount which was recorded under ## [Unreleased] in the changelog; happy to bump if you would prefer.
  • Documented under Notes in DOCS.md.

13 lines added, none removed. All three addon configs still parse as valid JSON and every mapped type is a valid Home Assistant addon folder.

🤖 Generated with Claude Code

cmatte and others added 2 commits September 20, 2026 05:02
The addon maps share, homeassistant_config and addon_config, but not the
standard Home Assistant `/ssl` directory. Certificates managed by addons such
as Let's Encrypt live there, so an MQTT TLS configuration pointing at them
fails at startup:

    error: z2m: MQTT failed to connect, exiting...
    (ENOENT: no such file or directory, open '/ssl/privkey.pem')

Copying the files into a mapped directory works but has to be redone on every
renewal, which defeats automated renewal; a symlink from the mapped config
directory is not followed.

Map `ssl` read-only, alongside the existing mappings. Read-only is sufficient:
the addon only needs to read the certificate and key, and the renewal is
performed by whichever addon manages them. Because the directory is mounted
rather than copied, renewals are picked up without further action.

Applied to both the stable and edge addons. The proxy addon is unchanged: it
does not connect to MQTT.

Closes zigbee2mqtt#835

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The reported issue covers two consumers of the Home Assistant `/ssl`
directory: the MQTT `cert`/`key` options and the frontend `ssl_cert`/`ssl_key`
options. The mount already serves both; say so, rather than documenting only
the MQTT case.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Koenkk
Koenkk merged commit deced45 into zigbee2mqtt:master Sep 22, 2026
5 checks passed
@Koenkk

Koenkk commented Sep 22, 2026

Copy link
Copy Markdown
Contributor

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cannot read /ssl folder - blocks SSL automated renewal setups

2 participants