HAPCTL(8)

NAME
hapctl - control utility for openhapd

SYNOPSIS
hapctl [-c file] [-s socket] command

DESCRIPTION
hapctl is the control utility of the openhapd(8) daemon. It checks the configuration file, it reports what the running daemon is doing, and it lists the devices.

status and devices ask the daemon over its control socket. The daemon answers from what it holds in memory. A file on disk holds what the daemon wrote at some earlier time, and the two disagree whenever the answer matters.

With no control socket, hapctl falls back to the PID file and to the configuration file, and it says which of the two answered. An operator thus always knows whether the report is live.

The options are:

-c file
    Read the configuration from file. The default is /etc/openhapd.conf.

-s socket
    Reach the daemon at socket. The default is /var/run/openhapd/control.sock. Use this when the control directive of openhapd.conf(5) names another path.

These commands are available:

check
    Parse openhapd.conf(5) and report what it holds. The command needs no daemon. It reports the line of the first error, and it exits 3 when the file does not parse.

    An absent configuration file is not an error. A fresh install has none, and the daemon then runs on its defaults.

status
    Report on the daemon: its name, its HAP port, its uptime, its pairing state and controller count, its configuration number, the number of loaded devices, the number of open connections, and the state of mDNS and MQTT.

    With no control socket, the command reports only whether a process is alive, from /var/run/openhapd.pid, and it names that file in its output.

devices
    List the devices. With a control socket, the command lists the accessories that the daemon really loaded, with the HomeKit accessory ID of each. Without one, it lists the device blocks of the configuration file, which is what the daemon would load at its next start.

help
    Show the usage message. Each command also takes -h.

FILES
/etc/openhapd.conf
    The default configuration file.
/var/run/openhapd/control.sock
    The control socket of the running daemon, mode 0600 in a directory of mode 0700.
/var/run/openhapd.pid
    The process ID of the daemon, read only when the control socket is not there.

hapctl opens no other file. It does not read /var/db/openhapd, and it creates nothing.

EXIT STATUS
The commands exit 0 on success.

check and devices exit 3 when the configuration file does not parse. Both read the same file through the same grammar.

An unknown command and a bad option exit 2.

status always exits 0. A stopped daemon is an answer, not a failure of the tool.

EXAMPLES
Check the configuration file:

    $ hapctl check
    Configuration file /etc/openhapd.conf is valid
      Configured devices: 3

Ask the running daemon what it is doing:

    $ hapctl status
    openhapd is running (Home Bridge)
      HAP port:          51827
      Uptime:            3d 4h 12m
      Pairing status:    paired (2 controllers)
      Configuration num: 7
      Devices:           3
      Connections:       1
      mDNS:              published
      MQTT:              connected

The same command with the daemon stopped:

    $ hapctl status
    openhapd is not running
      (read from /var/run/openhapd.pid: no control socket)

List the devices:

    $ hapctl devices
    Loaded devices: 2
      Bedroom Thermostat
        AID:   2
        Class: App::OpenHAP::Tasmota::Thermostat
        Topic: tasmota_AABBCC
        ID:    bedroom

Use a different configuration file:

    $ hapctl -c /etc/openhapd.test.conf check

DIAGNOSTICS
hapctl writes configuration errors to stderr. A line that the grammar does not accept names the file, the line number, and the reason:

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

status names the reason it could not reach the daemon. An absent socket and a refused connection are different problems:

      (read from /var/run/openhapd.pid: no control socket)
      (read from /var/run/openhapd.pid: Cannot reach /var/run/openhapd/control.sock: Permission denied)

The first is a stopped daemon, or one with control off in its configuration. The second is a running daemon that the caller may not reach. A caller who is neither root nor “_openhap” cannot search the directory of the socket, and thus cannot even see that the socket is there.

SEE ALSO
openhapd.conf(5), openhapd(8), rc(8)

HISTORY
The hapctl utility was first available with openhapd(8) in 2025. The control socket was added in 2026. Before that, status guessed the pairing state from the files under /var/db/openhapd.

AUTHORS
Dick Olsson <hi@senzilla.io>

CAVEATS
The control socket is mode 0600 in a directory of mode 0700, both owned by the “_openhap” user. A user who is neither root nor “_openhap” cannot reach it, and status then reports from the PID file only. That is the intended boundary: the reply names the devices and the controller count of the home.