Install nzyme on Ubuntu Server 24.04 (Noble Numbat)
Make sure to read the requirements and architecture guides before starting the installation process. Think about hardware requirements before you begin. Reach out using the community channels if you are unsure how to size the setup or what hardware to choose.
Warning
This guide assumes that you are starting with a fresh install of Ubuntu Server. Do not try to install nzyme on a Ubuntu Desktop system. It will not work.
Info
You do not have to install the nzyme-node
and nzyme-tap
components on the same type of operating system or
hardware. For example, you could install an nzyme-tap
on a Raspberry Pi OS and connect it to a nzyme-node
on
a more powerful server running Ubuntu Server.
Installing a nzyme-node
Install dependencies
First, we will install some dependencies:
This will install:
- Java 17 (OpenJDK) to run
nzyme-node
- PostgreSQL as our database (it will only listen on
127.0.0.1
by default)
Download and install nzyme-node
Download the nzyme-node
Debian .DEB
package from the downloads page. It does not
need architecture-specific packages and there is only one.
Download and install the nzyme-node
package:
Set up PostgreSQL
Next up, we will log into the PostgreSQL shell to issue commands that create a database called nzyme
and then a new
user called nzyme
with access to the database.
Make sure to replace your YOUR_PASSWORD_HERE
with a strong password for your database user. You will need it in the
next step.
sudo -u postgres psql
...
postgres=# CREATE DATABASE nzyme;
CREATE DATABASE
postgres=# CREATE USER nzyme WITH ENCRYPTED PASSWORD 'YOUR_PASSWORD_HERE';
CREATE ROLE
postgres=# GRANT ALL PRIVILEGES ON DATABASE nzyme TO nzyme;
GRANT
postgres=# \c nzyme
postgres=# GRANT CREATE ON SCHEMA public TO nzyme;
GRANT
postgres=# \q
Configure nzyme.conf
Now that we have a database and a database user, we can configure nzyme-node
.
Open the file /etc/nzyme/nzyme.conf
and edit at least the following settings:
Variable | Description |
---|---|
general.name |
The name of this nzyme node. If you are unsure, leave it at the default value. |
general.database_path |
URL to the PostgreSQL database you set up above. Make sure the host, database name, username and password are correct. |
interfaces.rest_listen_uri |
The URI that the REST API and web interface will listen on. Set this to a URL with an IP address you can reach from your workstation. The default is to listen on localhost only. You can set it to https://0.0.0.0:[port] to listen on all interfaces. |
interfaces.http_external_uri |
The address your browser will use to connect to the REST API of this node. Is likely the same as interfaces.rest_listen_uri when not running behind a load balancer or NAT. |
The last setting you have to confirm is in the /etc/default/nzyme
file. You will find the following line in it:
The parameters -Xms1g
and -Xmx1g
instruct the Java Virtual Machine (JVM) to immediately allocate and use 1 gigabyte
(1g
) of heap space. This is a good starting point, but you have to increase this value if you start to process more
data and see crashes with heap-related error messages. Configuring a too large heap space can lead to high CPU usage
caused by the garbage collector - that is why we are starting with a lower value.
Start nzyme
You can now enable and start the nzyme service. This will also make the service start up on boot automatically.
Now check the status of the nzyme service:
sudo systemctl status nzyme
...
● nzyme.service - Nzyme
Loaded: loaded (/lib/systemd/system/nzyme.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2023-07-27 19:38:57 CDT; 12s ago
Docs: https://github.com/lennartkoopmann/nzyme
Main PID: 15101 (nzyme)
Tasks: 22 (limit: 3933)
CPU: 32.409s
Note the Active: active (running)
. This means the system is running, and you should be able to reach the web interface
now.
If the service did not start successfully, check the /var/log/nzyme/nzyme.log
file or output of journalctl -xe
.
Access web interface
Once /var/log/nzyme/nzyme.log
shows a line like this, you are ready to go:
[main] INFO app.nzyme.core.rest.server.NzymeHttpServer - Started web interface and REST API at [https://172.16.0.191:22900/]. Access it at: [https://172.16.0.191:22900/]
Note that a nzyme-node
can take a while to finish the startup sequence on first launch because it will generate TLS
and PGP keys.
You can now open the nzyme web interface at the address you configured as interfaces.http_external_uri
above. Make sure
to use https://
because nzyme does not allow non-TLS HTTP. For example: https://172.16.0.50:22900/
That's it! You can configure your first user in the web interface and then continue to install your first tap.
Installing a nzyme-tap
To get the first data into our new nzyme setup, we have to install a nzyme-tap
.
Adding a new tap in the nzyme web interface
Before a tap is permitted to transmit any data, it must be first created in the nzyme web interface. Upon creation, a
unique leader secret will be generated for the tap. This can be thought of as a unique access key. Make sure to copy
this key as it will be used in the nzyme-tap
configuration file.
Taps and their associated permissions are integrated within nzyme's multi-tenancy model. When logged in as a super administrator or organization administrator, you can create new taps in the Taps section found under any Tenant. For instance, navigate as follows: Organizations -> Default Organization -> Tenants -> Default Tenant -> Taps.
Install nzyme-tap
package
Download the nzyme-tap
Debian .DEB
package from the downloads page. Make sure to pick the correct
distribution (2404noble
) and architecture (for example amd64
) for your hardware.
Download and install the nzyme-tap
package:
Configure nzyme-tap.conf
Start by creating a new tap the tenant authentication section of the nzyme web interface. It will provide you with a leader secret (think of it like an access key) that you will need for the tap configuration below.
Open the file /etc/nzyme/nzyme-tap.conf
and edit at least the following settings:
Variable | Description |
---|---|
general.leader_secret |
The leader secret for this tap, copied from the tap details page in the nzyme web interface |
general.leader_uri |
The HTTPs address of your nzyme-node or load balancer |
general.accept_insecure_certs |
Set to true or false . The default TLS certificate of nzyme-node is self-signed and considered insecure. Either set this to true and accept the risk or install your own TLS certificate. |
ethernet_interfaces.* |
Each block defines an Ethernet interface to listen on. For example, [ethernet_interfaces.enp6s0] would instruct the tap to record and process all packets seen on the interface enp6s0 . Use quotes if the interface name has special characters in it's name. |
wifi_interfaces.* |
Each block defines a WiFi interface to listen on. The tap will automatically configure it and set it into monitor mode. You can learn how to pick channels in the channel hopping documentation. Use quotes if the interface name has special characters in it's name. |
Tip
If you want to keep it simple, you can remove the ethernet_interface.*
and wifi_interfaces.*
configurations
entirely and add them later, using the WiFi and Ethernet
documentation. The tap will still start and register with the rest of nzyme, but simply not report any data yet.
Start the tap
You can now enable and start the tap service. This will also make the service start up on boot automatically.
Now check the status of the tap service:
sudo systemctl status nzyme-tap
...
● nzyme-tap.service - Nzyme-Tap
Loaded: loaded (/lib/systemd/system/nzyme-tap.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2023-07-27 20:57:30 CDT; 4min 31s ago
Docs: https://github.com/lennartkoopmann/nzyme
Main PID: 36099 (nzyme-tap)
Tasks: 130 (limit: 3933)
CPU: 1.737s
Note the Active: active (running)
. This means the tap is running, and you should be able to see the tap reporting
data in the nzyme web interface now.
If the service did not start successfully, check the output of journalctl -xe
.