Quick Start Guide

Install and configure WhiteOwl Network Monitoring.

System Requirements

Spec	Light (up to 10K FPS)	Production (up to 100K FPS)
CPU	8 cores	32 cores
RAM	16 GB	64 GB
Storage	500 GB SSD	2 TB SSD

• Ubuntu 24.04 LTS
• Internet access (for package downloads)
• Root or sudo privileges

Installation

1. Fill out the evaluation form on the homepage by selecting 'Request 30 Day Evaluation License'.

2. A token and license key will be emailed to you. Licenses expire 30 days from issue date (unless otherwise noted).

3. The confirmation page will include a link to download the install_script.sh to your home directory on the Linux host.

4. Copy install_script.sh to your home directory on the Linux host.

5. Make it executable:

   chmod +x install_script.sh

6. Run the installer:

   sudo ./install_script.sh

7. Follow the prompts:

   • License agreement — Select "Yes" to accept
   • Host IP — Verify the detected IP or enter a different one
   • Token — Paste the token from your email
   • License key — Press Enter, paste the key, then press Ctrl+D twice
   • PEM certificate — Press Enter, paste the PEM, then press Ctrl+D twice

8. When prompted about database backups:

   • New installation — Select "Yes" to load the Postgres and ClickHouse backups (creates required tables and base config)
   • Existing installation — Select "No" to preserve your data

Connecting to the UI

1. Open a browser
2. In the URL put https://<ip_of_host>
3. Login with default credentials admin/admin123

Basic Configuration

Add Sites

1. Click the Settings icon (upper right)
2. Select the Sites tab → Add Site
3. Include latitude/longitude for geo-map visualization
4. Alternatively, import sites from NetBox under the Integrations tab

SNMP Autodiscovery

1. Go to Settings → SNMP Autodiscovery tab
2. Click +Add Credentials and configure your SNMP community strings or v3 credentials
3. Click +Add Subnet — specify the subnet, assign a site, and select credentials
4. Click Run Now to start discovery

Tip: Enable LLDP on your devices to auto-generate topology maps under Topologies.

No SNMP

If you want to add devices without SNMP autodiscovery you can add them under settings/devices individually, using a csv or under settings/integrations using the Netbox integration. Visit Device Settings Documentation Visit Netbox Settings Documentation

Network Flow Data

WhiteOwl collects NetFlow, IPFIX, and sFlow from routers, switches, and firewalls.

Quick test with the built-in probe:

1. Go to Probe Management
2. Deploy a probe on the WhiteOwl host
3. TCP/IP flow data will appear in Flow Explorer

Production setup: Configure your network devices to export flows to the WhiteOwl host IP on the appropriate port (default: 2055 for NetFlow, 6343 for sFlow).

Enrichment

BGP and Geo visibility

In order to get full visibility including BGP, Geo etc sign up for a free Maxmind account.

1. Go to Settings (upper right)
2. Select Integrations
3. Add your Account ID and License Key
4. Select Save and Sync Now

Flow Tags

Add Flow Tags in order to enrich your traffic.

1. Go to Settings
2. Select Flow Tags
3. Add tags to enrich your flow data

Port Mappings

Add your own port to application name mappings

1. Go to Settings
2. Select Port Mappings
3. Add port to name mappings to enrich your flow data

Settings

Anthropic AI

To enable AI (chat, alerts, Executive report and MCP Server) you need to add your Anthropic API token to the /etc/chompy/.env file Find this line ANTHROPIC_API_KEY= and paste your key after

Restart the frontend

1. cd to /etc/chompy
2. sudo docker compose down frontend
3. sudo docker compose up -d frontend

AWS VPC Flow Logs

Visit Cloud Topology Documentation

To Enable VPC Flow logs you need to include your ACCESS KEY ID= and SECRET ACCESS KEY= in the /etc/chompy/.env file. Find the existing settings and add your Keys.

AWS_ACCESS_KEY_ID=

AWS_SECRET_ACCESS_KEY=

Also you need to include the region and sqs queue in the /etc/chompy/vector-config/vector.toml

[sources.vpc_flow_logs]

• type = "aws_s3"
• region = "us-east-2"
• strategy = "sqs"
• sqs.queue_url = "https://sqs.us-east-2.amazonaws.com/621528225508/vpc-flow-log-notifications"
• sqs.delete_message = true

and the following needs to match your s3 bucket name

• inputs = ["vpc_flow_logs"]

Restart the backend and vector

1. cd to /etc/chompy
2. sudo docker compose down backend
3. sudo docker compose up -d backend
4. sudo docker compose down vector
5. sudo docker compose up -d vector