ZendHQ Installation and Configuration

This topic describes the procedures for installing ZendHQ. ZendHQ is only available for PHP versions 7.2 and above on Linux.


ZendHQ has the following requirements:

  • ZendHQ is only available for PHP versions 7.2 and above on Linux, and 7.3 and above on Windows.
  • ZendHQ can be installed only on supported Linux platforms, except Ubuntu 16.04.
  • The ZendPHP repository must be installed.

Do not load XDebug and ZendHQ extensions at the same time. This applies to all supported ZendHQ platforms and supported PHP versions. Both extensions interact closely with PHP internals. This can cause conflicts between the extensions resulting in errors or invalid results for ZendHQ. For this reason, running the ZendHQ extension in parallel with XDebug is not supported.

Install the ZendHQ Service

To install the ZendHQ daemon, install the `zendhqd` package for your platform. The ZendHQ daemon can run on a ZendPHP server, or separately. If you are running ZendPHP on multiple servers, run the ZendHQ daemon on a separate server.

  1. Install the ZendPHP repository on your system before installing ZendHQ.
    Use either the zendphpctl repo-install script, or see the platform-specific ZendPHP installation documentation.

  2. Install ZendHQ for your platform.
    Choose one of the following options:

    • DEB-based systems: apt install zendhqd

    • RPM-based systems: yum install zendhqd and/or dnf install zendhqd

    • Alpine systems: apk add zendhqd

Install the ZendHQ PHP Extension

To enable the ZendHQ extension on servers running ZendPHP, install one of the following packages:

  • For RPM-based servers, install the `php{VERSION}zend-php-zendhq` package, where `{VERSION}` is the PHP minor version minus the dot separator.
    Example for PHP 8.3:
    yum install php83zend-php-zendhq
    dnf install php83zend-php-zendhq
  • For DEB-based servers, install the `php{VERSION}-zend-zendhq` package, where `{VERSION}` is the PHP minor version.

    Example for PHP 8.3:

    apt install php8.3-zend-zendhq
  • For Windows-based servers, there are three options; for more information, see Install the ZendHQ PHP Extension on Windows.
    Example for installing PHP 8.3 using the ZendPHP installation script on a server with IP address

    .\zendphp_install.ps1 install 8.3 -enable-all -with-deps mibs -set-system-path -zendhq -zendhqd-uri 'tcp://'


Install the license file. After getting your license from Zend Support, copy it to the file /opt/zend/zendphp/etc/license on the server where you have installed the ZendHQ daemon. The ZendHQ daemon is the holder of the license.

ZendHQ extension on Windows does not need a separate local license on the Windows machine. If the ZendHQ daemon has a valid license, the ZendHQ extension will work normally.

ZendHQ Node Configuration

Configure the server running the zendhqd so that:

  • It can communicate with ZendPHP nodes.
  • It can communicate with the ZendHQ User Interface.

These URIs are configured in the file /opt/zend/zendphp/etc/zendhqd.ini. The relevant settings for these are, with their defaults, respectively:

  • zendhqd.daemon_uri = tcp://
  • zendhqd.websocket.interface =

If you want the zendhqd.daemon_uri to listen to port 10090 on any IP address, use tcp:// To configure the zendhqd.websocket.interface setting to listen on any IP address, specify the port only, prefixed by `:`; For example, `:10091`.

For changes to take effect, restart the zendhqd daemon by running the following command:

systemctl restart zendhqd

ZendPHP Node Configuration

Configure your ZendPHP nodes to communicate with the ZendHQ node. Edit the configuration file for the extension, which is in one of the following locations:

  • RPM: /etc/opt/zend/php{VERSION}zend/php.d/90-zendhq.ini
    where {VERSION} is the PHP minor version, minus the . separator (e.g., 72, 80, 81).
  • DEB: /etc/php/{VERSION}-zend/mods-available/zendhq.ini
    where {VERSION} is the PHP minor version (e.g., 7.2, 8.0, 8.1).

Change the zendhq.daemon_uri setting so that it mirrors your zendhqd.daemon_uri setting. For example:

zendhq.daemon_uri = tcp://

You may specify the IP address OR a name that resolves to that IP address via DNS. (For example, with docker-compose or kubernetes, you might specify a service name for the ZendHQ node.)

If you are using PHP-FPM, restart your FPM process for the changes to take effect.
For example:

systemctl restart php7.4-zend-fpm

Changing the ZendHQ Token

ZendHQ uses an access token in order to authenticate users. By default, the token is "zendphp", and a sha256 hash of the value is stored as the zendhqd.session.auth_token_hash value in /opt/zend/zendphp/etc/zendhqd.ini.

To change the token, follow these steps:

  • Hash the new token; in the following command, replace {token value} with the new access token you wish to use, and run the command from a bash prompt:
    echo -n "{token value}" | sha256sum | awk '{ print $1 }'
  • Use the generated hash as the zendhqd.session.auth_token_hash value.
  • Restart the zendhqd daemon using the following command:
    systemctl restart zendhqd

You can also use the zendphpctl command to update he value.

zendphpctl zendhq-token {new token}

Customizing the UID/GID for the ZendHQ service

There's a user and group to set permissions of directories and files mounted through volumes, for example, the database directory or the cache directory in the application.

To customize the UID for this user, or the GID for this group, respectively, in your own installations, follow these steps.

Before installing the zendhqd package, create either the user or group, or both.


  • On any platform:

addgroup --system --gid 999 zendphp

  • For deb- and rpm-based Linux:

adduser --system --home /var/zendphp --shell /usr/sbin/nologin --uid 999 --ingroup zendphp zendphp

  • For Alpine Linux:

adduser --system --home /var/zendphp --shell /sbin/nologin --uid 999 --gid zendphp zendphp

Installing the ZendHQ User Interface

ZendHQ has a separate GUI for interacting with the daemon.

For more information about how to install it, see ZendHQ User Interface Installation.