Skip to main content
Version: 1.1.x

Installation on Ubuntu Server

This guide assumes that you have a freshly installed, recent Ubuntu 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.

This guide is based on Ubuntu Server 20.04.

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-12 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 ... 73229 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:

$ iwconfigenp0s3    no wireless extensions.
lo        no wireless extensions.
wlx9cefd5fd7c46  IEEE 802.11  ESSID:off/any          Mode:Managed  Access Point: Not-Associated   Tx-Power=0 dBm          Retry short  long limit:2   RTS thr:off   Fragment thr:off          Power Management:off

In my example here, I have one wireless adapter called wlx9cefd5fd7c46. If you are on a Debian-like distribution that is not Ubuntu, you might see the old, unpredictable naming scheme like wlan0, wlan1. In that case, it is strongly recommended to set up predictable interface naming.

To make sure that the adapters are always up but not attempting to do anything else (we only want them to listen to WiFi frames for nzyme), create a new file /etc/netplan/01-nzyme.yaml and configure your WiFi adapters from above to be up without any settings, like this:

network: version: 2 renderer: networkd ethernets:   wlx9cefd5fd7c46: {}

If you are using multiple WiFi adapters, simply add more lines like wlx9cefd5fd7c46: {} for each adapter.

After this, restart the machine and confirm that the adapters appear when running iwconfig.

Write down your WiFi interface names. We will use them 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.

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 → /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 (/lib/systemd/system/nzyme.service; enabled; vendor preset: enabled)     Active: active (running) since Sun 2020-09-06 22:13:37 UTC; 2s ago       Docs: https://github.com/lennartkoopmann/nzyme   Main PID: 1816 (nzyme)      Tasks: 13 (limit: 2282)     Memory: 70.1M     CGroup: /system.slice/nzyme.service             ├─1816 /bin/sh /usr/share/nzyme/bin/nzyme             └─1817 /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.