Path 2: Full Event Server

The ES is a Perl daemon that monitors ZoneMinder’s shared memory for new events, invokes the ML hooks, and handles push notifications, WebSockets, MQTT, rules, and more.

If you only want ML detection without the ES, see Path 1: Detection + Optional Push (no ES) instead.

Important

Prerequisites

The installer needs pip3 and — on Debian/Ubuntu — the python3-venv package to build the shared virtual environment. Install them before running install.sh:

  • Debian/Ubuntu: sudo apt install python3-pip python3-venv

  • Fedora/RHEL: sudo dnf install python3-pip

  • openSUSE: sudo zypper install python3-pip

  • Arch: sudo pacman -S python-pip

Without python3-venv, python3 -m venv still creates the directory but never bootstraps pip into it — you’ll end up with python/python3 in /opt/zoneminder/venv/bin but no pip. If that already happened, install the package above and run sudo /opt/zoneminder/venv/bin/python -m ensurepip --upgrade (or delete the venv and re-run the installer).

Step 1: Install ML dependencies

Follow Steps 1 and 2 from Path 1: Detection + Optional Push (no ES) to install OpenCV and pyzmNg. These are needed for the ML hooks that the ES invokes.

Step 2: Install the WebSocket Perl module

The installer handles most Perl dependencies via apt, but Net::WebSocket::Server must be installed separately:

sudo apt install make libprotocol-websocket-perl
sudo cpanm Net::WebSocket::Server

# If cpanm is not installed:
sudo apt install cpanminus

Step 3: Run the installer

git clone https://github.com/ZoneMinder/zmeventnotificationNg
cd zmeventnotificationNg
sudo -H ./install.sh    # say Yes to everything

Or, to run non-interactively:

sudo -H ./install.sh --install-es --install-es-config --install-hook --install-hook-config --no-interactive

This installs the ES, hooks, ML models, Perl dependencies (via apt), config files, and sets up the directory structure.

Note

The installer pulls in core pyzmNg automatically. If you need additional pyzmNg extras (remote ML server, training UI, etc.) or want to install a local development version of pyzmNg, see the pyzmNg installation guide.

Note

By default install.sh places the ES script in /usr/bin. If your ZM install uses a different path (e.g. /usr/local/bin), edit the TARGET_BIN variable in install.sh before running it.

Step 4: Set up SSL

The ES runs in secure (WSS) mode by default and requires SSL certificates. If you already use SSL for ZoneMinder, just point the ES to those same certs.

If you don’t have certificates yet — generate self-signed ones:

sudo openssl req -x509 -nodes -days 4096 -newkey rsa:2048 \
    -keyout /etc/zm/apache2/ssl/zoneminder.key \
    -out /etc/zm/apache2/ssl/zoneminder.crt

Important

Set the Common Name to the hostname or IP you’ll use to access the server (e.g. myserver.ddns.net).

For zmNinjaNG picture messaging, you need a real certificate (e.g. LetsEncrypt) — self-signed won’t work for that.

Step 5: Configure

The installer creates these config files (all YAML):

  • /etc/zm/zmeventnotification.yml — ES settings

  • /etc/zm/objectconfig.yml — ML detection settings

  • /etc/zm/secrets.yml — credentials (ZM portal, SSL paths)

  • /etc/zm/es_rules.yml — notification rules

At minimum, edit /etc/zm/secrets.yml:

secrets:
  ZM_USER: your_username
  ZM_PASSWORD: your_password
  ZM_PORTAL: "https://your-server/zm"
  ZM_API_PORTAL: "https://your-server/zm/api"
  ES_CERT_FILE: /etc/zm/apache2/ssl/zoneminder.crt
  ES_KEY_FILE: /etc/zm/apache2/ssl/zoneminder.key

Then update the SSL paths in zmeventnotification.yml:

ssl:
  cert: /etc/zm/apache2/ssl/zoneminder.crt
  key: /etc/zm/apache2/ssl/zoneminder.key

If you are not using ML hooks, set use_hooks: "no" in the customize section of zmeventnotification.yml.

If you are behind a firewall, open port 9000 (TCP, bi-directional).

Step 6: Test manually

First, verify the ES version:

sudo -u www-data /usr/bin/zmeventnotification.pl --version

You should see 7.0.0 or above. If not, re-run the installer to update.

Then test manually before enabling daemon mode:

sudo -u www-data /usr/bin/zmeventnotification.pl --debug

This starts the ES in the foreground with debug output. Check that it loads without errors, then Ctrl+C to stop.

The -u www-data is important — the ES must run as the same user as your web server (may be apache on some systems).

Step 7: Enable auto-start

In the ZoneMinder web interface, go to Options -> Systems and enable OPT_USE_EVENTNOTIFICATION. The ES will now start automatically with ZoneMinder.

Step 8: Set up ML hooks

Follow Steps 4–6 from Path 1: Detection + Optional Push (no ES) to configure objectconfig.yml, verify versions, and test detection.

Note

With the ES, you do not set EventStartCommand in ZoneMinder — the ES handles event detection itself. Don’t configure both or you’ll run detection twice.

Logging

For quick debugging, add --debug when running manually. For proper persistent logging, see Logging.

Optional: MQTT

If you want MQTT notifications:

sudo cpanm Net::MQTT::Simple

MQTT 3.1.1 or newer is required.

Troubleshooting

If something isn’t working, see Machine Learning Hooks FAQ for debugging steps and common issues.