OPENHAPD.CONF(5)

NAME
openhapd.conf - OpenHAP daemon configuration file

DESCRIPTION
openhapd.conf is the configuration file for the openhapd(8) daemon. The file uses a simple key-value format with device blocks that define HomeKit accessories.

SYNTAX
A setting is a key and a value on one line. Both “key value” and “key = value” parse. The two forms mean the same thing, thus a file can use either.

Leading and trailing whitespace does not matter. A value in double quotes loses the quotes, thus a value can hold a space:

    hap_name = "Living Room Bridge"
    hap_port 51827

A ‘#’ starts a comment that runs to the end of the line. The grammar has no escape for it, thus no value can hold a ‘#’. An empty line does nothing.

A block is a type, one or more arguments, and an opening brace. The settings of the block follow, and a ‘}’ on its own line ends it. A block cannot hold a block.

The daemon refuses to start on a line that it cannot parse. It reports the file, the line number, and the reason:

    openhapd: /etc/openhapd.conf:14: cannot parse: hap_prt 51827

The daemon never skips a line it did not understand. A typo that a parser ignores is a setting that does not apply, and the operator has no way to see it. Fix the line and start the daemon again.

GLOBAL OPTIONS
These global options are available:

hap_name string
    The name of the HomeKit bridge, as the iOS Home app shows it. Default: “OpenHAP Bridge”.

hap_port number
    The TCP port for the HAP server. Default: 51827.

hap_pin XXXX-XXXX
    The 8-digit setup code for pairing. The format is XXXX-XXXX. Each X is a digit 0-9. The dashes only make the code easy to read. The daemon removes them when it parses the value. The HAP specification does not permit these values (after removal of the dashes): 00000000, 11111111, 22222222, 33333333, 44444444, 55555555, 66666666, 77777777, 88888888, 99999999, 12345678, 87654321. The daemon refuses a malformed or not-permitted code at startup, before it detaches from the terminal. Default: 1995-1018.

db_path path
    The directory that holds the pairing database and the cryptographic keys. Default: /var/db/openhapd.

control path | off
    The UNIX socket where hapctl(8) asks the running daemon what it is doing. Default: /var/run/openhapd/control.sock.

    The daemon creates the directory of the socket while it is still root, with owner “_openhap” and mode 0700, because OpenBSD clears /var/run at boot. The socket itself is mode 0600. A user who is neither root nor “_openhap” thus cannot reach it.

    The value off runs the daemon with no control channel. hapctl(8) then reports from /var/run/openhapd.pid only, and it says so.

    No reply on this socket carries a secret: not the setup code, not the MQTT password, and no key.

log_level level
    The log verbosity level. The valid values are: debug, info, notice, warning, error. The daemon refuses any other value at startup and names it. Default: info.

log_facility facility
    The syslog facility for the log messages. The valid values are: daemon, local0–local7, user. Default: daemon.

mqtt_host hostname
    The hostname or the IP address of the MQTT broker. Default: 127.0.0.1.

mqtt_port number
    The TCP port of the MQTT broker. Default: 1883.

mqtt_user username
    The username for MQTT authentication. This option is optional.

mqtt_pass password
    The password for MQTT authentication. This option is optional.

DEVICE BLOCKS
Define each device with this syntax:

    device <type> <subtype> <id> {
        name = "<display name>"
        topic = "<mqtt topic>"
        [more options...]
    }

The parameters are:

type
    The device driver type. At this time, only tasmota is available.

subtype
    The device subtype. For tasmota, the valid values are: thermostat, heater, sensor.

id  The unique identifier of the device in the configuration. The daemon uses it for internal reference.

name
    The display name that the iOS Home app shows. This option is necessary.

topic
    The MQTT topic prefix for the device. For Tasmota devices, this is the topic from the MQTT settings of the device. The default of that setting is “tasmota_%06X”. The %06X part is the last 6 hex digits of the MAC address. This option is necessary.

The other options are different for each device subtype:

  Sensor Options
Tasmota sensor devices have this option:

has_humidity 0 | 1
    Add a HomeKit humidity service beside the temperature service. Set it to 1 for a sensor that reports a Humidity field, for example a DHT22. Default: 0.

FILES
/etc/openhapd.conf
    The default location of the configuration file.
/etc/examples/openhapd.conf
    The example configuration file that make install installs.

EXAMPLES
A minimal configuration with one thermostat:

    hap_name = "Home Bridge"
    hap_pin = 9876-5432
    mqtt_host = 192.168.1.10
    device tasmota thermostat bedroom {
        name = "Bedroom Thermostat"
        topic = tasmota_AABBCC
    }

Three devices with custom MQTT settings:

    hap_name = "OpenHAP"
    hap_port = 51827
    hap_pin = 1112-2333
    mqtt_host = mqtt.local
    mqtt_port = 1883
    mqtt_user = homekit
    mqtt_pass = secretpassword
    log_level = debug
    log_facility = local0
    device tasmota thermostat bedroom {
        name = "Bedroom"
        topic = tasmota_AABBCC
    }
    device tasmota thermostat living_room {
        name = "Living Room"
        topic = tasmota_DDEEFF
    }
    device tasmota thermostat kitchen {
        name = "Kitchen"
        topic = tasmota_112233
    }

SEE ALSO
syslog.conf(5), hapctl(8), mdnsd(8), mosquitto(8), openhapd(8)

STANDARDS
The MQTT topic structure obeys the Tasmota firmware conventions. See https://tasmota.github.io/docs/MQTT/ for more data on the Tasmota MQTT topics.

HISTORY
The openhapd.conf file format was first available with openhapd(8) in 2025.

AUTHORS
Dick Olsson <hi@senzilla.io>

CAVEATS
The configuration file holds the hap_pin in plain text. Make sure that the file permissions are correct: mode 0600, with root as the owner.

If you change the hap_name or the hap_pin after pairing, it can be necessary to pair all controllers again.

The file holds mqtt_pass in plain text, and the daemon sends it to the broker without encryption. openhapd(8) does not use MQTT over TLS. Keep the broker on the local machine or on a trusted network.