Install and upgrade

Requirements

Use case	Requirement
Go service / Wasm analysis	Linux; the prebuilt package needs no compiler or separate Wasm runtime
Network capture	A visible interface and effective capture permissions; restrict mirrored traffic upstream
OpenSSL / Go TLS	Linux ≥ 5.15, kernel BTF, a root probe, and a supported target runtime
Go QUIC / HTTP/3	Linux ≥ 5.17, target ELF symbols and DWARF, and a supported quic-go version

This guide targets the latest 0.3.0-dev development snapshot, build ID 0.3.0-dev-20261018-5e1320d3. Linux arm64 has OrbStack runtime evidence. amd64 has only been cross-compiled, with no complete package on this page. See versioned downloads and support limits.

The main CLI is a static Go binary. The latest package's eCapture helper also requires glibc ≥ 2.34 and system libpcap.so.0.8. The verified reference environment is Debian 13; the installer does not install system libraries. After extraction, run ldd lib/ecapture-probe and check for not found. Other distributions still need kernel, library and probe validation.

Install a candidate package

Get every part from downloads, verify them, and reconstruct netflowscout-linux-arm64.tar.gz using that page's commands. If you already extracted it there, enter the corresponding nfs-version directory and run sudo sh deploy/install.sh directly. The following is for an archive that has been reconstructed but not extracted:

sha256sum -c netflowscout-linux-arm64.tar.gz.sha256
mkdir netflowscout-package
tar -xzf netflowscout-linux-arm64.tar.gz -C netflowscout-package
cd netflowscout-package
sudo sh deploy/install.sh

Replace arm64 with the delivered architecture. The installer checks internal SHA256SUMS, creates a system user and directories, and installs services and plugins. It does not start capture automatically. Checksums establish integrity, not publisher authentication.

Path	Purpose
/usr/local/bin/netflowscout	CLI and service executable
/usr/local/lib/netflowscout/plugins	Administrator-installed Wasm packages
/etc/netflowscout/netflowscout.json	Main configuration, root:netflowscout / 0640
/etc/netflowscout/endpoints/	Endpoint configurations, root / 0600
/var/lib/netflowscout/	Private WAL and local events

Configure and start

First-install wizard

sudo netflowscout init --lang en

For Chinese, use sudo netflowscout init --lang zh.

The fresh installer leaves configuration files absent and prints the wizard command. The wizard selects a service, sensor ID, endpoint or network capture, and local file or local plus Dataway output. Endpoint mode asks for the real executable, probe, protocol and role. Network mode lists local interfaces and requires an explicit interface and filter. Installation identity, existing files and directory writability are checked before questions. The writable check creates and removes a private temporary file without creating the configuration directory. Filters use the live capture grammar and can be corrected in place without losing earlier answers. Enter accepts a default; choices ignore case. Save confirmation accepts yes/no, y/n, or 是/否. Use :quit, Ctrl+C or EOF to cancel. Protocol choices retain the names declared by installed plugins. If names differ only in case, enter the declared spelling to resolve ambiguity.

Wasm, schemas, rules and configuration are validated in a private temporary directory before a summary is shown. The final default is no; enter yes to save netflowscout.json, rules-observability.nfs, and, for endpoint mode, endpoints/app.json. Installed main/rule files are root:netflowscout / 0640; the endpoint file is root / 0600. Events are redacted; raw recording and verification canaries remain disabled. Tune rule thresholds afterwards. Each file is written and synced privately in its destination directory, then published atomically without replacement; the main configuration is published last. Failure cleanup checks file identity. Multiple files are still not a power-loss transaction. Validation does not prove capture or delivery.

For Dataway, enter a credential-free base URL and an environment variable name. Set its value afterwards in root-managed /etc/netflowscout/output.env (0600), loaded by systemd. The wizard never requests a token. doctor checks its own environment and does not automatically read this file.

Existing files are never overwritten, including placeholders from older installers. Manage existing installations using netflowscout tui --control or the configuration change workflow. init --dir /NEW_DIRECTORY --plugins /absolute/plugins creates private 0600 reference files. They still use deployment paths under /run/netflowscout and /var/lib/netflowscout, so this is not an isolated runtime sandbox. Stock systemd units do not use custom directories. Direct startup commands for reference configurations are omitted; first install the files or configure independent socket, WAL, output paths and units. Use configure for scripted generation.

The save phase does not start services. Interactive installed-path initialization can offer setup with explicit confirmation; see Setup & investigation. Manual preflight and startup remain available:

sudo netflowscout check --config /etc/netflowscout/netflowscout.json
sudo netflowscout doctor --config /etc/netflowscout/netflowscout.json \
  --endpoint-config /etc/netflowscout/endpoints/app.json
sudo systemctl enable --now netflowscout.service netflowscout-analyzer.service
sudo systemctl enable --now netflowscout-discovery@app.service

Network mode does not need discovery. Follow the endpoint guide for TLS plaintext. Wait for attached after startup, then verify actual business traffic.

Upgrade and roll back

sudo netflowscout upgrade --package /path/netflowscout-linux-arm64.tar.gz
sudo netflowscout rollback

Upgrade validates the package and complete candidate plugin/rule set before stopping services. It backs up files, updates the executable, probes, BPF objects, plugins, and units, then restores previously active services. Failures trigger a recovery attempt. Administrator plugins are retained; conflicts are rejected before stopping services.

Rollback restores the previous version and configuration. The WAL, compatible rule checkpoints, and logs remain in place. Arbitrary version-to-version data migration is not guaranteed. Do not mix incompatible probes, BPF objects, or schemas. Restarts create capture gaps that cannot be replayed from the application.

After saving at the installed path, interactive init can continue to setup with explicit confirmation. It also supports :back, summary edit and running application selection. See Setup & investigation.