All settings

This page contains all currently supported settings in configuration.yaml.

NOTE

The code blocks show an example value for each setting (may be the default or any value derived from the possibilities/examples/boundaries).

advanced

Advanced

log_rotation

advanced:
    log_rotation: true

Type: boolean
Default: true
Restart required to be effective

log_console_json

advanced:
    log_console_json: false

Type: boolean
Default: false
Restart required to be effective

log_symlink_current

Create symlink to current logs in the log directory

advanced:
    log_symlink_current: false

Type: boolean
Default: false
Restart required to be effective

log_output

Output location of the log, leave empty to suppress logging

advanced:
    log_output: ['console', 'file']

Type: array of string
Default: ["console","file"]
Possible array values: console, file, syslog
Restart required to be effective

log_directory

Location of log directory

advanced:
    log_directory: 'data/log/%TIMESTAMP%'

Type: string
Examples:
- "data/log/%TIMESTAMP%"
Restart required to be effective

log_file

Log file name, can also contain timestamp

advanced:
    log_file: 'log.log'

Type: string
Default: "log.log"
Examples:
- "zigbee2mqtt_%TIMESTAMP%.log"
Restart required to be effective

log_level

Logging level

advanced:
    log_level: 'info'

Type: string
Default: "info"
Possible values: error, warning, info, debug

log_namespaced_levels

Set individual log levels for certain namespaces

advanced:
    log_namespaced_levels: {}

Type: object
Default: {}
Examples:
- {"z2m:mqtt":"warning"}
- {"zh:ember:uart:ash":"info"}

log_debug_to_mqtt_frontend

Log debug level to MQTT and frontend (may decrease overall performance)

advanced:
    log_debug_to_mqtt_frontend: false

Type: boolean
Default: false
Restart required to be effective

log_debug_namespace_ignore

Do not log these namespaces (regex-based) for debug level

advanced:
    log_debug_namespace_ignore: ''

Type: string
Default: ""
Examples:
- "^zhc:legacy:fz:(tuya|moes)"
- "^zhc:legacy:fz:(tuya|moes)|^zh:ember:uart:|^zh:controller"

log_directories_to_keep

Number of log directories to keep before deleting the oldest one

advanced:
    log_directories_to_keep: 10

Type: number
Default: 10
Minimum: 5
Maximum: 1000

channel

Zigbee channel, changing might require re-pairing some devices! (Note: use a ZLL channel: 11, 15, 20, or 25 to avoid problems)

advanced:
    channel: 11

Type: number
Default: 11
Minimum: 11
Maximum: 26
Examples:
- 15
- 20
- 25
Restart required to be effective

adapter_concurrent

Adapter concurrency (e.g. 2 for CC2531 or 16 for CC26X2R1) (default: null, uses recommended value)

advanced:
    adapter_concurrent: null

Type: number,null
Minimum: 1
Maximum: 64
Restart required to be effective

adapter_delay

advanced:
    adapter_delay: null

Type: number,null
Minimum: 0
Maximum: 1000
Restart required to be effective

last_seen

Add a last_seen attribute to MQTT messages, contains date/time of last Zigbee message

advanced:
    last_seen: 'disable'

Type: string
Default: "disable"
Possible values: disable, ISO_8601, ISO_8601_local, epoch

timestamp_format

Log timestamp format

advanced:
    timestamp_format: 'YYYY-MM-DD HH:mm:ss'

Type: string
Default: "YYYY-MM-DD HH:mm:ss"
Examples:
- "YYYY-MM-DD HH:mm:ss.SSS"
Restart required to be effective

transmit_power

Transmit power of adapter, only available for Z-Stack (CC253*/CC2652/CC1352) adapters, CC2652 = 5dbm, CC1352 max is = 20dbm (5dbm default)

advanced:
    transmit_power: null

Type: number,null
Minimum: -128
Maximum: 127
Restart required to be effective

Examples when 'state' of a device is published json: topic: 'zigbee2mqtt/my_bulb' payload '{"state": "ON"}' attribute: topic 'zigbee2mqtt/my_bulb/state' payload 'ON' attribute_and_json: both json and attribute (see above)

advanced:
    output: 'json'

Type: string
Default: "json"
Possible values: attribute_and_json, attribute, json
log_syslog
syslog (enabled)
host

The host running syslogd, defaults to localhost.

advanced:
    log_syslog:
        host: 'localhost'

Type: string
Default: "localhost"

port

The port on the host that syslog is running on, defaults to syslogd's default port.

advanced:
    log_syslog:
        port: 514

Type: number
Default: 514

protocol

The network protocol to log over (e.g. tcp4, udp4, tls4, unix, unix-connect, etc).

advanced:
    log_syslog:
        protocol: 'udp4'

Type: string
Default: "udp4"
Examples:
- "udp4"
- "tls4"
- "unix"
- "unix-connect"

path

The path to the syslog dgram socket (i.e. /dev/log or /var/run/syslog for OS X).

advanced:
    log_syslog:
        path: '/dev/log'

Type: string
Default: "/dev/log"
Examples:
- "/var/run/syslog"

pid

PID of the process that log messages are coming from (Default process.pid).

advanced:
    log_syslog:
        pid: 'process.pid'

Type: string
Default: "process.pid"

localhost

Host to indicate that log messages are coming from (Default: localhost).

advanced:
    log_syslog:
        localhost: 'localhost'

Type: string
Default: "localhost"

type

The type of the syslog protocol to use (Default: BSD, also valid: 5424).

advanced:
    log_syslog:
        type: '5424'

Type: string
Default: "5424"

app_name

The name of the application (Default: Zigbee2MQTT).

advanced:
    log_syslog:
        app_name: 'Zigbee2MQTT'

Type: string
Default: "Zigbee2MQTT"

eol

The end of line character to be added to the end of the message (Default: Message without modifications).

advanced:
    log_syslog:
        eol: '/n'

Type: string
Default: "/n"

log_syslog

syslog (disabled)

advanced:
    log_syslog: null

Type: null

pan_id

Pan ID (string)

advanced:
    pan_id: 'abc'

Type: string
Default: 6754

pan_id

Pan ID (number)

advanced:
    pan_id: 1

Type: number
Default: 6754
Minimum: 1
Maximum: 65534

ext_pan_id

Extended pan ID (string)

advanced:
    ext_pan_id: 'abc'

Type: string
Default: [221,221,221,221,221,221,221,221]

ext_pan_id

Extended pan ID (array)

advanced:
    ext_pan_id: []

Type: array of number
Default: [221,221,221,221,221,221,221,221]

network_key

Network key(string)

advanced:
    network_key: 'abc'

Type: string
Default: [1,3,5,7,9,11,13,15,0,2,4,6,8,10,12,13]

network_key

Network key(array)

advanced:
    network_key: []

Type: array of number
Default: [1,3,5,7,9,11,13,15,0,2,4,6,8,10,12,13]

availability

Availability

enabled

Enable availability checks

availability:
    enabled: false

Type: boolean
Default: false
Restart required to be effective

active

Active

timeout *

Time after which an active device will be marked as offline in minutes

availability:
    active:
        timeout: 10

Type: number
Default: 10
Minimum: 1
Restart required to be effective

max_jitter

Maximum jitter (in msec) allowed on timeout to avoid availability pings trying to trigger around the same time

availability:
    active:
        max_jitter: 30000

Type: number
Default: 30000
Minimum: 1000

backoff

Enable timeout backoff on failed availability pings (x1.5, x3, x6, x12...)

availability:
    active:
        backoff: true

Type: boolean
Default: true

pause_on_backoff_gt

Pause availability pings when backoff reaches over this limit until a new Zigbee message is received from the device. A value of zero disables pausing.

availability:
    active:
        pause_on_backoff_gt: 0

Type: number
Default: 0
Minimum: 0

passive

Passive

timeout *

Time after which an passive device will be marked as offline in minutes

availability:
    passive:
        timeout: 1500

Type: number
Default: 1500
Minimum: 1
Restart required to be effective

devices

friendly_name *

Used in the MQTT topic of a device. By default this is the device ID

devices:
    '0x1234567812345678':
        friendly_name: 'abc'

Type: string

retain

Retain MQTT messages of this device

devices:
    '0x1234567812345678':
        retain: true

Type: boolean

disabled

Disables the device (excludes device from network scans, availability and group state updates)

devices:
    '0x1234567812345678':
        disabled: true

Type: boolean
Restart required to be effective

retention

Sets the MQTT Message Expiry in seconds, Make sure to set mqtt.version to 5

devices:
    '0x1234567812345678':
        retention: 0

Type: number

qos

QoS level for MQTT messages of this device

devices:
    '0x1234567812345678':
        qos: null

Type: number
Possible values: 0, 1, 2

throttle

The minimum time between payloads in seconds. Payloads received whilst the device is being throttled will be discarded

devices:
    '0x1234567812345678':
        throttle: 0

Type: number
Restart required to be effective

debounce

Debounces messages of this device

devices:
    '0x1234567812345678':
        debounce: 0

Type: number
Restart required to be effective

debounce_ignore

Protects unique payload values of specified payload properties from overriding within debounce time

devices:
    '0x1234567812345678':
        debounce_ignore: 'action'

Type: array of string
Examples:
- "action"

optimistic

Publish optimistic state after set

devices:
    '0x1234567812345678':
        optimistic: true

Type: boolean
Default: true

filtered_attributes

Filter attributes with regex from published payload.

devices:
    '0x1234567812345678':
        filtered_attributes: '^temperature$'

Type: array of string
Examples:
- "^temperature$"
- "^battery$"
- "^action$"

filtered_cache

Filter attributes with regex from being added to the cache, this prevents the attribute from being in the published payload when the value didn't change.

devices:
    '0x1234567812345678':
        filtered_cache: '^input_actions$'

Type: array of string
Examples:
- "^input_actions$"

filtered_optimistic

Filter attributes with regex from optimistic publish payload when calling /set. (This has no effect if optimistic is set to false).

devices:
    '0x1234567812345678':
        filtered_optimistic: '^color_(mode|temp)$'

Type: array of string
Examples:
- "^color_(mode|temp)$"
- "color"

icon

The user-defined device icon for the frontend. It can be a full URL link to an image (e.g. https://SOME.SITE/MODEL123.jpg) or a path to a local file inside the device_icons directory (e.g. device_icons/MODEL123.png).

devices:
    '0x1234567812345678':
        icon: 'abc'

Type: string

homeassistant

Home Assistant

name

Name of the device in Home Assistant

devices:
    '0x1234567812345678':
        homeassistant:
            name: 'abc'

Type: string

frontend

Frontend

enabled

Enable frontend

frontend:
    enabled: false

Type: boolean
Default: false
Restart required to be effective

package

Package used for the frontend

frontend:
    package: 'zigbee2mqtt-frontend'

Type: string
Default: "zigbee2mqtt-frontend"
Possible values: zigbee2mqtt-frontend, zigbee2mqtt-windfront
Restart required to be effective

port

Frontend binding port. Ignored when using a unix domain socket

frontend:
    port: 8080

Type: number
Default: 8080
Restart required to be effective

host

Frontend binding host. Binds to a unix socket when an absolute path is given instead.

frontend:
    host: null

Type: string,null
Examples:
- "127.0.0.1"
- "::1"
- "/run/zigbee2mqtt/zigbee2mqtt.sock"
Restart required to be effective

auth_token

Enables authentication, disabled by default

frontend:
    auth_token: null

Type: string,null
Restart required to be effective

url

URL on which the frontend can be reached, currently only used for the Home Assistant device configuration page

frontend:
    url: null

Type: string,null
Restart required to be effective

ssl_cert

SSL Certificate file path for exposing HTTPS. The sibling property 'ssl_key' must be set for HTTPS to be activated.

frontend:
    ssl_cert: null

Type: string,null
Restart required to be effective

ssl_key

SSL key file path for exposing HTTPS. The sibling property 'ssl_cert' must be set for HTTPS to be activated.

frontend:
    ssl_key: null

Type: string,null
Restart required to be effective

base_url

Base URL for the frontend. If hosted under a subpath, e.g. 'http://localhost:8080/z2m', set this to '/z2m'

frontend:
    base_url: '/'

Type: string
Default: "/"
Restart required to be effective

notification_filter

Hide frontend notifications matching specified regex strings. Example: 'z2m: Failed to ping.*'

frontend:
    notification_filter: []

Type: array of string

disable_ui_serving

If true, the frontend UI is not served, only the WebSocket is maintained by Zigbee2MQTT (you are required to serve a standalone UI yourself as needed).

frontend:
    disable_ui_serving: null

Type: boolean,null
Restart required to be effective

groups

friendly_name *

groups:
    1:
        friendly_name: 'abc'

Type: string

retain

groups:
    1:
        retain: true

Type: boolean

optimistic

groups:
    1:
        optimistic: true

Type: boolean

qos

QoS level for MQTT messages of this group

groups:
    1:
        qos: null

Type: number
Possible values: 0, 1, 2

off_state

Control when to publish state OFF or CLOSE for a group. 'all_members_off': only publish state OFF/CLOSE when all group members are in state OFF/CLOSE, 'last_member_state': publish state OFF whenever one of its members changes to OFF

groups:
    1:
        off_state: 'all_members_off'

Type: string
Default: "all_members_off"
Possible values: all_members_off, last_member_state
Restart required to be effective

filtered_attributes

groups:
    1:
        filtered_attributes: []

Type: array of string

health

Health

interval

Interval between checks in minutes

health:
    interval: 10

Type: number
Default: 10
Minimum: 1
Restart required to be effective

reset_on_check

If true, will reset stats every time the health check is executed (only applicable to stats that can be reset).

health:
    reset_on_check: false

Type: boolean
Default: false

homeassistant

Home Assistant integration

enabled

Enable Home Assistant integration

homeassistant:
    enabled: false

Type: boolean
Default: false
Restart required to be effective

discovery_topic

Home Assistant discovery topic

homeassistant:
    discovery_topic: 'homeassistant'

Type: string
Default: "homeassistant"
Examples:
- "homeassistant"
Restart required to be effective

status_topic

homeassistant:
    status_topic: 'homeassistant/status'

Type: string
Default: "homeassistant/status"
Examples:
- "homeassistant/status"
Restart required to be effective

legacy_action_sensor

Home Assistant legacy actions sensor, when enabled a action sensor will be discoverd and an empty action will be send after every published action.

homeassistant:
    legacy_action_sensor: false

Type: boolean
Default: false

experimental_event_entities

Home Assistant experimental event entities, when enabled Zigbee2MQTT will add event entities for exposed actions. The events and attributes are currently deemed experimental and subject to change.

homeassistant:
    experimental_event_entities: false

Type: boolean
Default: false

map_options

Networkmap

graphviz

colors

fill

enddevice

map_options:
    graphviz:
        colors:
            fill:
                enddevice: '#fff8ce'

Type: string
Default: "#fff8ce"

coordinator

map_options:
    graphviz:
        colors:
            fill:
                coordinator: '#e04e5d'

Type: string
Default: "#e04e5d"

router

map_options:
    graphviz:
        colors:
            fill:
                router: '#4ea3e0'

Type: string
Default: "#4ea3e0"

font

enddevice

map_options:
    graphviz:
        colors:
            font:
                enddevice: '#000000'

Type: string
Default: "#000000"

coordinator

map_options:
    graphviz:
        colors:
            font:
                coordinator: '#ffffff'

Type: string
Default: "#ffffff"

router

map_options:
    graphviz:
        colors:
            font:
                router: '#ffffff'

Type: string
Default: "#ffffff"

line

active

map_options:
    graphviz:
        colors:
            line:
                active: '#009900'

Type: string
Default: "#009900"

inactive

map_options:
    graphviz:
        colors:
            line:
                inactive: '#994444'

Type: string
Default: "#994444"

mqtt

MQTT

base_topic

MQTT base topic for Zigbee2MQTT MQTT messages

mqtt:
    base_topic: 'zigbee2mqtt'

Type: string
Default: "zigbee2mqtt"
Examples:
- "zigbee2mqtt"
Restart required to be effective

server *

MQTT server URL (use mqtts:// for SSL/TLS connection)

mqtt:
    server: 'mqtt://localhost:1883'

Type: string
Examples:
- "mqtt://localhost:1883"
Restart required to be effective

keepalive

MQTT keepalive in second

mqtt:
    keepalive: 60

Type: number
Default: 60
Restart required to be effective

ca

Absolute path to SSL/TLS certificate of CA used to sign server and client certificates

mqtt:
    ca: '/etc/ssl/mqtt-ca.crt'

Type: string
Examples:
- "/etc/ssl/mqtt-ca.crt"
Restart required to be effective

key

Absolute path to SSL/TLS key for client-authentication

mqtt:
    key: '/etc/ssl/mqtt-client.key'

Type: string
Examples:
- "/etc/ssl/mqtt-client.key"
Restart required to be effective

cert

Absolute path to SSL/TLS certificate for client-authentication

mqtt:
    cert: '/etc/ssl/mqtt-client.crt'

Type: string
Examples:
- "/etc/ssl/mqtt-client.crt"
Restart required to be effective

user

MQTT server authentication user

mqtt:
    user: 'johnnysilverhand'

Type: string
Examples:
- "johnnysilverhand"
Restart required to be effective

password

MQTT server authentication password

mqtt:
    password: 'ILOVEPELMENI'

Type: string
Examples:
- "ILOVEPELMENI"
Restart required to be effective

client_id

MQTT client ID

mqtt:
    client_id: 'MY_CLIENT_ID'

Type: string
Examples:
- "MY_CLIENT_ID"
Restart required to be effective

reject_unauthorized

Disable self-signed SSL certificate

mqtt:
    reject_unauthorized: true

Type: boolean
Default: true
Restart required to be effective

include_device_information

Include device information to mqtt messages

mqtt:
    include_device_information: false

Type: boolean
Default: false

version

MQTT protocol version

mqtt:
    version: 4

Type: number,null
Default: 4
Examples:
- 5
Restart required to be effective

force_disable_retain

Disable retain for all send messages. ONLY enable if your MQTT broker doesn't support retained message (e.g. AWS IoT core, Azure IoT Hub, Google Cloud IoT core, IBM Watson IoT Platform). Enabling will break the Home Assistant integration

mqtt:
    force_disable_retain: false

Type: boolean
Default: false
Restart required to be effective

maximum_packet_size

Specifies the maximum allowed packet length (in bytes) that the server can send to Zigbee2MQTT. NOTE: The same value exists in your MQTT broker but for the length the client can send to it instead.

mqtt:
    maximum_packet_size: 1048576

Type: number
Default: 1048576
Minimum: 20
Maximum: 268435456
Restart required to be effective

ota

OTA updates

update_check_interval

Your device may request a check for a new firmware update. This value determines how frequently third party servers may actually be contacted to look for firmware updates. The value is set in minutes, and the default is 1 day.

ota:
    update_check_interval: 1440

Type: number
Default: 1440
Minimum: 1

disable_automatic_update_check

Zigbee devices may request a firmware update, and do so frequently, causing Zigbee2MQTT to reach out to third party servers. If you disable these device initiated checks, you can still initiate a firmware update check manually.

ota:
    disable_automatic_update_check: false

Type: boolean
Default: false

zigbee_ota_override_index_location

Location of override OTA index file

ota:
    zigbee_ota_override_index_location: null

Type: string,null
Examples:
- "index.json"
Restart required to be effective

image_block_response_delay

Limits the rate of requests (in milliseconds) during OTA updates to reduce network congestion. You can increase this value if your network appears unstable during OTA.

ota:
    image_block_response_delay: 250

Type: number
Default: 250
Minimum: 50
Restart required to be effective

default_maximum_data_size

The size of file chunks sent during an update (in bytes). Note: This value may get ignored for manufacturers that require specific values.

ota:
    default_maximum_data_size: 50

Type: number
Default: 50
Minimum: 10
Maximum: 100
Restart required to be effective

serial

Serial

port

Location of the adapter. To autodetect the port, set null

serial:
    port: null

Type: string,null
Examples:
- "/dev/ttyACM0"
Restart required to be effective

disable_led

Disable LED of the adapter if supported

serial:
    disable_led: false

Type: boolean
Default: false
Restart required to be effective

adapter

Adapter type, not needed unless you are experiencing problems

serial:
    adapter: 'deconz'

Type: string
Possible values: deconz, zstack, zigate, ezsp, ember, zboss, zoh
Restart required to be effective

baudrate

Baud rate speed for the serial port. This must match what the firmware on your adapter supports (most commonly 115200).

serial:
    baudrate: 115200

Type: number
Examples:
- 115200
- 921600
- 460800
- 230400
- 57600
- 38400
Restart required to be effective

rtscts

RTS / CTS Hardware Flow Control for serial port

serial:
    rtscts: true

Type: boolean
Restart required to be effective

blocklist

Block devices from the network (by ieeeAddr)

blocklist: []

Type: array of string
Restart required to be effective

device_options

Options that are applied to all devices

device_options: {}

Type: object

passlist

Allow only certain devices to join the network (by ieeeAddr). Note that all devices not on the passlist will be removed from the network!

passlist: []

Type: array of string
Restart required to be effective