Install nzyme on Ubuntu Server 22.04 (Jammy Jellyfish)

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:

sudo apt update && sudo apt install -y openjdk-17-jre-headless postgresql-14

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:

wget [url_to_nzyme_deb_package]
sudo dpkg -i nzyme-node_ubuntu-2204jammy-noarch-x.x.x.deb

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=# \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:

NZYME_JAVA_OPTS="-Xms1g -Xmx1g -XX:-OmitStackTraceInFastThrow"

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.

sudo systemctl enable nzyme
sudo systemctl start nzyme

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 (2204jammy) and architecture (for example amd64) for your hardware.

Download and install the nzyme-tap package:

wget [url_to_nzyme_deb_package]
sudo dpkg -i nzyme-tap_ubuntu-2204jammy-amd64-x.x.x.deb

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.

sudo systemctl enable nzyme-tap
sudo systemctl start nzyme-tap

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.