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 dependenciesWe 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 nzymeNow 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 adaptersMake 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 PostgreSQLBefore 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 nzymeThe 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 nzymeThat'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.