view release on metacpan or  search on metacpan

man/openhap/openhapd.conf.5  view on Meta::CPAN

.\" $OpenBSD$
.\"
.\" Copyright (c) 2025 Dick Olsson <hi@senzilla.io>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: August 2 2026 $
.Dt OPENHAPD.CONF 5
.Os
.Sh NAME
.Nm openhapd.conf
.Nd OpenHAP daemon configuration file
.Sh DESCRIPTION
.Nm
is the configuration file for the
.Xr openhapd 8
daemon.
The file uses a simple key-value format with device blocks that
define HomeKit accessories.
.Sh SYNTAX
A setting is a key and a value on one line.
Both
.Dq Ic key Ar value
and
.Dq Ic key No = Ar value
parse.
The two forms mean the same thing, thus a file can use either.
.Pp
Leading and trailing whitespace does not matter.
A value in double quotes loses the quotes, thus a value can hold a
space:
.Bd -literal -offset indent
hap_name = "Living Room Bridge"
hap_port 51827
.Ed
.Pp
A
.Sq #
starts a comment that runs to the end of the line.
The grammar has no escape for it, thus no value can hold a
.Sq # .
An empty line does nothing.
.Pp
A block is a type, one or more arguments, and an opening brace.
The settings of the block follow, and a
.Sq }
on its own line ends it.
A block cannot hold a block.
.Pp
The daemon refuses to start on a line that it cannot parse.
It reports the file, the line number, and the reason:
.Bd -literal -offset indent
openhapd: /etc/openhapd.conf:14: cannot parse: hap_prt 51827
.Ed
.Pp
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.
.Sh GLOBAL OPTIONS
These global options are available:
.Bl -tag -width Ds
.It Ic hap_name Ar string
The name of the HomeKit bridge, as the iOS Home app shows it.
Default:
.Dq OpenHAP Bridge .
.It Ic hap_port Ar number
The TCP port for the HAP server.
Default: 51827.
.It Ic hap_pin Ar 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.
.It Ic db_path Ar path
The directory that holds the pairing database and the cryptographic
keys.
Default:
.Pa /var/db/openhapd .
.It Ic control Ar path | Cm off
The UNIX socket where
.Xr hapctl 8
asks the running daemon what it is doing.
Default:
.Pa /var/run/openhapd/control.sock .
.Pp
The daemon creates the directory of the socket while it is still
root, with owner
.Dq _openhap
and mode 0700, because
.Ox