OPENHAPD.CONF(5) File Formats Manual OPENHAPD.CONF(5)

openhapd.conf — OpenHAP daemon configuration file

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.

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.

These global options are available:

string
The name of the HomeKit bridge, as the iOS Home app shows it. Default: “OpenHAP Bridge”.
number
The TCP port for the HAP server. Default: 51827.
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.
path
The directory that holds the pairing database and the cryptographic keys. Default: /var/db/openhapd.
path |
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.

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.
facility
The syslog facility for the log messages. The valid values are: daemon, local0–local7, user. Default: daemon.
hostname
The hostname or the IP address of the MQTT broker. Default: 127.0.0.1.
number
The TCP port of the MQTT broker. Default: 1883.
username
The username for MQTT authentication. This option is optional.
password
The password for MQTT authentication. This option is optional.

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.
The display name that the iOS Home app shows. This option is necessary.
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:

Tasmota sensor devices have this option:

0 |
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.

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

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
}

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

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

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

Dick Olsson <hi@senzilla.io>

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.

August 2, 2026 OpenBSD