Securing the installation

A useful way to think about Zigbee2MQTT in terms of security is to compare it to the software running on a network router: it provides configuration and control of a network. As such, it is, by default, only locally accessible.

With Zigbee2MQTT being a bridge, the various software components attached to it (MQTT broker, automation software, etc.) must each be secured properly as well. Refer to their respective documentation.

Exposing any of these components publicly requires careful security planning. Untrusted access must never be permitted.

Host system

• Dedicated user: run Zigbee2MQTT under a dedicated, unprivileged user account (not root). This limits the blast radius if the process is ever compromised.
• Restrict data directory access: the data directory contains the full configuration, network state, and device data. Only the Zigbee2MQTT user should have access to it.
• Keep the host system up to date: apply operating system and dependency (Node.js, MQTT broker, etc.) security updates regularly and keep Zigbee2MQTT itself updated.

Configuration file

The configuration.yaml file contains sensitive information such as MQTT credentials and the Zigbee network key.

• Restrict file permissions: ensure only the user running Zigbee2MQTT can read/write the file.

  chmod 600 configuration.yaml
  

• Use a secrets file: avoid storing credentials in plain text in configuration.yaml. Instead, use a separate secret.yaml file referenced with the !secret.yaml syntax. See Specifying in a different file.

  Apply the same permission restriction to secret.yaml:

  chmod 600 secret.yaml
  

MQTT

MQTT is the primary entry point in and out of Zigbee2MQTT. It is used to publish data and to control every aspect of Zigbee2MQTT (configuration, network, devices, etc.).

See MQTT configuration for the full reference.

Frontend

The frontend uses the same API as MQTT, but wrapped in a WebSocket for in-browser access. Anyone who can reach the frontend has full control over Zigbee2MQTT, same as MQTT.

Authentication

Enable token-based authentication with the auth_token option.

Use the same precautions as any password. Store it in secret.yaml (see Configuration file) rather than directly in configuration.yaml.

Encryption (HTTPS / WSS)

Enable HTTPS/WSS directly within Zigbee2MQTT by providing a certificate and private key.

Alternatively, terminate TLS at a reverse proxy (Nginx, Apache, etc.) placed in front of the frontend. See Frontend configuration for proxy configuration examples.

Bind address

By default, the frontend listens on all interfaces (0.0.0.0). If remote access is not required, restrict it to localhost:

frontend:
    host: 127.0.0.1

Alternatively, use a Unix socket to avoid any network exposure:

frontend:
    host: '/run/zigbee2mqtt/zigbee2mqtt.sock'

Zigbee network

Network encryption key

Zigbee communication is encrypted using a 128-bit network key.

To generate a new random key on next startup, use Onboarding, or update it manually:

advanced:
    network_key: GENERATE

Zigbee2MQTT will replace GENERATE with a randomly generated key on startup. Of course, you can also set a specific key manually.

See Zigbee network configuration for more details.

PAN ID and Extended PAN ID

The PAN ID and Extended PAN ID identify your network. These are not security measures.

Changing them is possible and requires re-pairing all devices. This is mostly done in case you need to avoid a conflict with another nearby network.

IEEE and Network addresses

The IEEE and Network addresses identify your devices. These are not security measures.

The IEEE address is statically assigned to the Zigbee chip in the device (although it can be changed in some cases). Two devices with the same IEEE address cannot join a same network.

The Network Address is randomly assigned on device join and usually remains the same until reset/rejoin (although it may change at the discretion of the device).

Joining (permit join)

The "permit join" state determines whether new devices are allowed to join the network. Joining is enabled temporarily (for 254 seconds by default) via the dedicated frontend button or via MQTT. You can also close the joining window manually once pairing is complete.

Install codes

Joining with an install code provides better security (if available). A code is randomly assigned during the manufacturing process of a device. The code allows to encrypt the initial network key transport from the Trust Center (coordinator) to the joining device.

Ask the vendor or refer to each device's documentation to check if an install code is available (usually printed on the device, plainly or as a QR code). Codes can be added through the frontend. See also Add install code via MQTT.

Device passlist and blocklist

For stricter control over which devices are allowed on the network, use a passlist or blocklist. See Device blocklist / passlist for more details.

Inter-PAN

Inter-PAN messages are unsecured messages sent to or received from unjoined devices 1-hop away. Touchlink (previously known as ZLL) uses inter-PAN messaging.

Inter-PAN is usually reserved for highly specific operations (e.g. resetting a device to factory settings via Touchlink), undesired messages are aggressively dropped, and close physical proximity is required. This limits the impact of its lack of security.

Zigbee 4.0

Zigbee 4.0 provides several security enhancements. You can read more about it in the announcement from the CSA: https://csa-iot.org/newsroom/the-connectivity-standards-alliance-announces-zigbee-4-0-and-suzi-empowering-the-next-generation-of-secure-interoperable-iot-devices/

NOTE: It will take time before devices catch up to the new standard and support all these enhancements.

External extensions and converters

By design, external extensions and converters execute arbitrary user-provided JavaScript code within the Zigbee2MQTT process. This grants significant customization flexibility, but also means that malicious or buggy code can compromise the entire Zigbee2MQTT instance, and potentially the host system.

Firmware updates (OTA)

Firmware updates can provide bug fixes, security updates and other welcomed features. However, they can also change device behavior in ways that may affect Zigbee2MQTT compatibility and potentially introduce buggy, or even malicious functionality. Review the release notes before applying a firmware update. See OTA updates for more details.

By default, Zigbee2MQTT matches and retrieves OTA images from the Koenkk/zigbee-OTA repository. This repository is a mirror of manufacturer-provided firmware updates, both manually and automatically curated.