Installation

Install DHCP DPI on a fresh Linux VM in two steps: install the deb packages, then run the installer.

DHCP DPI ships as a small set of Debian (.deb) packages plus an interactive installer that wires everything together (ClickHouse, nginx, nftables, system tuning, user accounts, services). You will not be building anything from source — the binaries inside the package are ready to run.

What You Need

A dedicated Linux VM (or LXC container) running a modern Debian-based distribution, with the deb packages we shipped you.

Item	Requirement
OS	Ubuntu 24.04 LTS or newer / Debian 12 or newer (any Debian-based distro with `dpkg`)
Kernel	6.x or later (default on the OSes above)
Architecture	`amd64`
Hardware	2 vCPU / 4 GB RAM / 40 GB disk for evaluation; 4 vCPU / 8 GB RAM / 100 GB disk for steady-state 4k req/s and a few weeks of event retention; scale up for higher rates or longer retention
Network	At least one interface that sees DHCP traffic (or receives mirrored copies)
Privileges	`root` / `sudo` on the VM
Internet (during install)	Mandatory. The installer pulls most of its dependencies from the distribution’s apt repositories and ClickHouse straight from the ClickHouse project’s package repository. Air-gapped installs are not supported out of the box — you would have to pre-mirror every dependency yourself.

The recommended unit of deployment is a single VM (or LXC container) dedicated to DHCP DPI. Co-residency with the DHCP server is possible but introduces caveats (see Deployment Modes -> Collocated Deployment).

Packages You Receive

Package	Required?	Purpose
`dhcp-dpi_<version>_amd64.deb`	Required	Core appliance: packet processor, API/GUI, nftables ruleset, ClickHouse schema, support backchannel
`dhcp-dpi-tileserver_<version>_amd64.deb`	Optional	Map tile server for the geolocation flow visualiser (map data is sideloaded separately; see chapter 21)
`dhcp-dpi-simulator_<version>_amd64.deb`	Optional	DHCP traffic simulator used for testing and benchmarking

Only the core dhcp-dpi package is needed for a working deployment.

Installation

Step 1 — Install the deb packages

Copy the deb(s) to the VM and install them with dpkg:

sudo dpkg -i dhcp-dpi_<version>_amd64.deb
# optional extras (install only what you need):
sudo dpkg -i dhcp-dpi-tileserver_<version>_amd64.deb
sudo dpkg -i dhcp-dpi-simulator_<version>_amd64.deb

If dpkg reports missing dependencies, resolve them in one step:

sudo apt-get install -f

After this step the binaries and config templates are unpacked under /opt/dhcp-dpi/, but the services are not yet configured or started.

Step 2 — Run the installer

The installer wires the appliance into the VM: ClickHouse schema, nginx (for HTTPS), nftables ruleset, system tuning (file descriptor limits, sysctls), user accounts, and systemd units.

Interactive (recommended for first install):

sudo /opt/dhcp-dpi/share/install/install.sh

The installer prompts for:

ClickHouse location (local install by default)
Database name (default DHCP_DPI_01)
Network interface to inspect (auto-detected)
DHCP scope: IPv4-only, IPv6-only, or dualstack (default dualstack)
Whether to enable the LLM backend (default off — you can enable it later)
Initial admin and operator passwords

Non-interactive (for automation / re-installs):

sudo /opt/dhcp-dpi/share/install/install.sh --yes

With --yes the installer accepts every default. Admin and operator passwords are taken from the environment variables DHCP_DPI_ADMIN_PASSWORD and DHCP_DPI_OPERATOR_PASSWORD; if either is unset, a random password is generated and printed on stdout at the end of the run — capture it before closing the terminal.

The installer is idempotent: re-running it on a working appliance reapplies configuration without rotating already-set passwords or wiping data.

Step 3 — Confirm it is up

Three quick checks:

# Services running
systemctl status dhcp-processor dhcp-dpi-api nginx clickhouse-server

# nftables ruleset loaded
sudo nft list table inet dhcp_inspection | head

# GUI reachable
curl -k https://localhost/api/health

Open https://<vm-ip>/ in a browser and log in with the admin credentials from Step 2.

Next Steps

Deployment Modes — choose inline vs. mirrored, common topologies, raw-socket caveats.
nftables Deployment — what the shipped ruleset does and how to verify it.
Configuration Reference — every config.yaml key with defaults.
User Management — create operator/viewer accounts and configure SSO.
Optional AI-driven anomaly detection is available; its setup ships with the install package.

Uninstall

To remove the appliance:

sudo /opt/dhcp-dpi/share/install/dpi-uninstall.sh
sudo dpkg --purge dhcp-dpi dhcp-dpi-tileserver dhcp-dpi-simulator

The uninstaller stops services, removes the nftables table, and offers to drop the ClickHouse database. The deb purge removes the binaries and configuration directories.