This guide assumes that you have a freshly installed, recent Raspberry Pi OS in front of you and that you have gone through your standard hardening and configuration procedure to set up things like user accounts, timezones and locales.
It is also a good idea to take a look a the Architecture first.
The guide is based on the Raspberry Pi OS Lite release based on Debian Buster (Released on August 08 2020).
We will not be using the onboard WiFi of the Rasbperry Pi, but an external Panda PAU09. See Requirements.
It is a good idea to use a Raspberry Pi 4 (2 GB RAM is totally fine, 4 GB is more fun) but nzyme is also actively tested on older Pi 3 models.
If you decide to use the on-board WiFi chip instead of an ethernet cable for network connectivity, please make sure to follow this additional
configuration guide in the Other Common Problems section of the knowledge base.
We start by installing Java 11 (OpenJDK), PostgreSQL (the database server used by nzyme) and
libpcap (for capturing WiFi frames):
$ sudo apt update && sudo apt install -y libpcap0.8 openjdk-11-jre-headless postgresql-11 wireless-tools
Now download the nzyme Debian from the downloads page to your server:
$ wget [http-url-to-nzyme-debian-package]
Install nzyme using the
deb file you just downloaded:
$ sudo dpkg -i nzyme-1.0.0-beta.1.debSelecting previously unselected package nzyme.(Reading database ... 42572 files and directories currently installed.)Preparing to unpack nzyme-1.0.0-beta.1.deb ...Unpacking nzyme (1.0.0~beta.1) ...Setting up nzyme (1.0.0~beta.1) ...
Make sure your WiFi adapters are plugged in and confirm that you can see them using the
$ iwconfigeth0 no wireless extensions. wlan0 IEEE 802.11 ESSID:off/any Mode:Managed Access Point: Not-Associated Retry short limit:7 RTS thr:off Fragment thr:off Power Management:on wlan1 IEEE 802.11 ESSID:off/any Mode:Managed Access Point: Not-Associated Tx-Power=20 dBm Retry short long limit:2 RTS thr:off Fragment thr:off Power Management:off lo no wireless extensions.
If you see, like in this case, the old, unpredictable naming scheme like
wlan1, it is strongly recommended
to set up predictable interface naming.
I enabled predictable interface naming and see it in effect now:
$ iwconfigeth0 no wireless extensions. wlx9cefd5fbc13d IEEE 802.11 ESSID:off/any Mode:Managed Access Point: Not-Associated Tx-Power=20 dBm Retry short long limit:2 RTS thr:off Fragment thr:off Power Management:off wlan0 IEEE 802.11 ESSID:off/any Mode:Managed Access Point: Not-Associated Retry short limit:7 RTS thr:off Fragment thr:off Power Management:on lo no wireless extensions.
Write down your WiFi interface name (
wlx9cefd5fbc13d in my case). We will use it in the nzyme configuration later.
Before we can run nzyme, we have to create a PostgreSQL database:
$ sudo -u postgres psqlpostgres=# create database nzyme;CREATE DATABASEpostgres=# create user nzyme with encrypted password 'YOUR_PASSWORD_HERE';CREATE ROLEpostgres=# grant all privileges on database nzyme to nzyme;GRANTpostgres=# \q
psql shell with Ctrl+d. Write down the database name, username and password. You will need it later in the
nzyme configuration file.
deb package you installed earlier wrote an example configuration file that we can copy to the standard nzyme
$ sudo cp /etc/nzyme/nzyme.conf.example /etc/nzyme/nzyme.conf
We have to configure the following parameters:
Set this to a unique ID of your nzyme installation. It must be unique (in your environment) and contain only alphanumeric characters, underscores and dashes.
This is the SHA256 hash of your nzyme administrator password. You can create the hash of your password like this:
$ echo -n secretpassword | sha256sum
This is the connection string that nzyme uses to connect to the PostgreSQL database you created earlier. You must at least change the password.
The default configuration file points to a Python 3.8 installation, which your Raspberry Pi will most likely not
have. Change it to Python 3.7, which is installed by default:
Here we configure where our web interface and REST APIs are listening. Please follow the comments in the configuration file or read more in the configuration reference
This is where you list all WiFi adapters you want to use to scan the environment. Pay attention to the
setting to make sure that each channel is only scanned by one adapter. An adapter can scan as many channels as you
wish, as long as it supports that channel. You can find a list of all supported channels by connected WiFi adapter
iwlist channel command.
See also: Network Monitoring.
Every configuration option is explained in detail in the configuration reference.
That's it! We are ready to enable and start nzyme.
This will configure nzyme to start automatically when the system boots:
$ sudo systemctl enable nzymeCreated symlink /etc/systemd/system/multi-user.target.wants/nzyme.service → /usr/lib/systemd/system/nzyme.service.
Now start nzyme like this:
$ sudo systemctl start nzyme
Check if it started successfully:
$ sudo systemctl status nzyme● nzyme.service - Nzyme Loaded: loaded (/usr/lib/systemd/system/nzyme.service; enabled; vendor preset: enabled) Active: active (running) since Fri 2020-09-25 22:36:54 BST; 6s ago Docs: https://github.com/lennartkoopmann/nzyme Main PID: 1396 (nzyme) Tasks: 18 (limit: 4915) CGroup: /system.slice/nzyme.service ├─1396 /bin/sh /usr/share/nzyme/bin/nzyme └─1397 /usr/bin/java -jar -Dlog4j.configurationFile=file:///etc/nzyme/log4j2-debian.xml /usr/share/nzyme/nzyme.jar -c /etc/nzyme/nzyme.conf
If the status command does not show nzyme as running (
Active: active (running)), there is an issue with the
configuration. You can check the nzyme log file with
tail -n 200 /var/log/nzyme/nzyme.log. If that log file
does not exist, there is an issue with starting nzyme. Run
journalctl -xe to find out what happened.
You should now be able to open the nzyme web interface at the address you configured in the
settings and log in with the password you configured. (remember, the SHA256 hash?) Your username is
Take a look at Authentication
to learn more.
Make sure that all probes are showing as running. If they indicate any issues, look at the nzyme log file to
find out why.
Log rotation is enabled by default. You can change logging and log rotation settings in /etc/nzyme/log4j2-debian.xml.
It is recommended to restart the whole machine to make sure that all services come back automatically as expected.
Next up, configure your networks to be monitored.