Skip to main content
Version: Next

Installation on Raspberry Pi

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 wpa_supplicant configuration guide in the Other Common Problems section of the knowledge base.

Step 1: Install dependencies#

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

Step 2: Download and install nzyme#

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) ...

Step 3: Configure your WiFi adapters#

Make sure your WiFi adapters are plugged in and confirm that you can see them using the iwconfig command:

$ 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 wlan0, 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.

Step 4: Set up PostgreSQL#

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

Exit the psql shell with Ctrl+d. Write down the database name, username and password. You will need it later in the nzyme configuration file.

Step 5: Configure nzyme#

The deb package you installed earlier wrote an example configuration file that we can copy to the standard nzyme configuration path:

$ sudo cp /etc/nzyme/nzyme.conf.example /etc/nzyme/nzyme.conf

We have to configure the following parameters:

general.id#

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.

general.admin_password_hash#

This is the SHA256 hash of your nzyme administrator password. You can create the hash of your password like this:

$ echo -n secretpassword | sha256sum

Username is admin.

general.database_path#

This is the connection string that nzyme uses to connect to the PostgreSQL database you created earlier. You must at least change the password.

general.python.path#

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: path: /usr/bin/python3.7

interfaces.*#

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

802_11_monitors.*#

This is where you list all WiFi adapters you want to use to scan the environment. Pay attention to the channels 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 using the iwlist channel command.

See also: Network Monitoring.

Every configuration option is explained in detail in the configuration reference.

Step 6: Start nzyme#

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 interfaces.* settings and log in with the password you configured. (remember, the SHA256 hash?) Your username is admin. 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.