Run DENIS on a small Linux machine or Raspberry Pi

What you need

• A Linux machine on x86-64 or ARM64 with systemd (Ubuntu, Debian, Raspberry Pi OS, RHEL-family and others) or OpenRC (Alpine). A Raspberry Pi 4 or 5 needs a 64-bit system.
• A wired connection to the network you want to watch, and root access.
• For personal, non-commercial use the Community edition is free on up to 100 devices.

Steps

1. Check the architecture

   x86_64 is an ordinary PC or server; aarch64 is ARM64, such as a Raspberry Pi with a 64-bit system. The installer picks the right build for you; the check matters only if you download the program by hand.

   $ uname -m

2. Optional: look around with the demo first

   Download the program for your platform from the latest release, then load the built-in demo. It serves the console on this machine only, with a fictional company of 42 devices, no packet capture and no login. Open http://localhost:8080.

   $ mv denis-* denis && chmod +x denis
   $ ./denis demo --db demo.db load && ./denis serve --db demo.db --insecure-no-auth

3. Install DENIS as a service

   The installer downloads the release from GitHub, checks its signature and checksum, creates an unprivileged denis user, sets DENIS up as a service, picks a free port and prints the address and a one-time admin password. It runs as root, so read it first.

   Add --dry-run to download and verify without changing anything. Debian, Ubuntu and Raspberry Pi OS get the usual build, which uses the system’s libpcap; Alpine and other systems get the static build.

   $ curl -fLO https://github.com/stefanmesaros/denis/releases/latest/download/install.sh
   $ less install.sh      # it runs as root: read it first
   $ sudo bash install.sh

4. Sign in

   Open the address the installer printed. DENIS uses HTTPS with a certificate it created itself, so the browser warns once; you can trust the DENIS certificate authority or install your own certificate. Sign in as admin with the one-time password and choose your own (at least 12 characters).

5. Work through the first hour

   The setup guide opens by itself. In order: look at the Devices page and open a device to see why DENIS thinks it is what it is; tick “needs review” and confirm the devices you know; describe your important devices (owner, location, criticality); add a notification channel and press Test; add a passkey or an authenticator app to your account.

   For the first 24 hours DENIS learns what is normal and does not alert on new devices and destinations. Judge the alerts after that.

6. See more than your own segment

   From an ordinary switch port DENIS discovers the devices on its segment, but it sees only its own traffic. To see who talks to whom, connect it to a mirror port or a tap, as described in the next guide.

Troubleshooting

• “Address already in use”Another program took the port. The installer picks a free port; if it was taken later, change the port in /etc/denis/env and restart the service. When running by hand, use --listen 127.0.0.1:9000 and open that port.
• No devices appearCheck that DENIS listens on the right network interface (Settings → Capture) and has permission to capture. The troubleshooting guide in the documentation lists the common causes.
• The browser warns about the certificateExpected on first use: the certificate is self-signed. Trust the DENIS CA or install your own certificate, as the deployment guide describes.
• A security product reports a port scanExpected: on IT networks DENIS sends an ARP sweep, a ping and a light port scan. Switch them off in Settings → Capture, or run with --passive-only, and see “Security tools that may flag DENIS”.

Known limitations

In the documentation

• Quick start
• Deployment
• Troubleshooting
• Security tools that may flag DENIS

Next guide: SPAN port and TAP placement

Something did not work as described? Tell us on GitHub or in the community.