Probe Deployment
Probe Deployment provides a centralized interface for deploying, upgrading, configuring, and managing WhiteOwl monitoring probes across your network. Probes are lightweight agents that perform packet capture, SNMP monitoring, synthetic testing, and flow export from remote network segments. All deployment and management operations are executed via Ansible over SSH.
The page is organized into six tabs: New Deployment, Upgrade Probes, Job History, Config Template, Config Backups, and VPN Setup.
Probe Binary
The header bar displays the current probe binary available for deployment:
- Binary path — The location of the probe binary on the WhiteOwl server (e.g.,
/app/releases/chompy-probe-latest). - Size — The binary file size (e.g.,
11.2 MB). - Status indicator — A green checkmark confirms the binary is present and ready for deployment.
Click Refresh at any time to re-check the binary status.
New Deployment
The New Deployment tab is where you deploy fresh probes to remote hosts.
Deployment Targets
Each target defines a remote host where a probe will be installed. Click + Add Target to add additional targets for batch deployment.
| Field | Description |
|---|---|
| The probe currently runs on Ubuntu 22 and 24 hosts - Ubuntu 24.04 recommended | |
| Target IP / Hostname | The IP address or resolvable hostname of the remote host (e.g., 192.168.1.100 or ec2-instance.us-east-2.compute.amazonaws.com). Hostnames are resolved to IP addresses at deployment time. |
| Probe Name | A friendly name for this probe (e.g., probe-site1, probe-dallas). This becomes the probe's identity in WhiteOwl. |
| Site | The site to associate this probe with. Select from configured sites or leave unassigned. |
| Capture Interface | The network interface the probe should capture packets on (e.g., eth0, ens192). Set to any to capture on all interfaces. |
SSH Authentication
Probes are deployed over SSH. Two authentication methods are supported:
| Method | Description |
|---|---|
| Password | Enter the SSH username (default: root) and password. |
| PEM Key | Upload a .pem or .key private key file for key-based authentication. This is the recommended method for cloud deployments (e.g., AWS EC2 instances). NOTE: PEM Files are deleted after they are used. They are not stored in the database today. |
SSH credentials are saved to the device record in the database and can be edited later under Settings → Devices.
SSH Credential Security
All SSH credentials are encrypted at rest using AES-256-GCM authenticated encryption before being stored in the PostgreSQL database. This applies to SSH passwords, enable passwords, and any other sensitive credential fields.
How It Works
- When you enter credentials during probe deployment (or later via Settings → Devices), the backend encrypts them before writing to the database.
- A random 16-byte initialization vector (IV) is generated for each encryption operation, ensuring that the same password never produces the same ciphertext.
- An authentication tag is generated to provide tamper detection — if the stored value is modified outside of WhiteOwl, decryption will fail rather than returning corrupted data.
- The encrypted value is stored as a text string in the format:
iv:authTag:encryptedData(all hex-encoded). - At execution time (deployment, upgrade, config push), credentials are decrypted in memory, passed to Ansible, and never written to disk in plaintext.
Encryption Key
The encryption key is configured via the ENCRYPTION_KEY environment variable on the WhiteOwl server. This must be a 64-character hex string representing 32 bytes (AES-256).
To generate a key:
openssl rand -hex 32
Add the key to your environment (e.g., in your Docker Compose or .env file):
ENCRYPTION_KEY=your_64_character_hex_key_here
If the encryption key is lost, all stored credentials become unrecoverable and must be re-entered for every device. Back up the key securely. Do not commit it to version control.
Database Schema
SSH credentials are stored in the devices table as TEXT columns:
| Column | Description |
|---|---|
ssh_username | The SSH username (stored in plaintext — not sensitive). |
ssh_password | The SSH password (AES-256-GCM encrypted). |
enable_password | The enable/privileged EXEC password (AES-256-GCM encrypted). Required for Cisco IOS devices. |
The centralized encryption module (backend/utils/crypto.js) is shared across all WhiteOwl features that handle sensitive data, including SNMP community strings, ensuring consistent security throughout the platform.
Probe Features
Toggle optional capabilities for the probe via checkboxes:
| Feature | Default | Description |
|---|---|---|
| SNI capture | ✅ Enabled | Captures TLS Server Name Indication (SNI) from HTTPS traffic for application-level visibility without decryption. |
| WireGuard VPN | ☐ Disabled | Installs WireGuard on the probe and configures a VPN tunnel back to the WhiteOwl central server. Required for probes deployed on remote networks that cannot directly reach the central server. See VPN Setup for server-side configuration. |
| SNMP monitoring | ✅ Enabled | Installs SNMP tools on the probe host, enabling the probe to perform SNMP polling of local network devices. |
| Traceroute tools | ✅ Enabled | Installs traceroute utilities on the probe host for synthetic traceroute testing. |
Deploying
- Fill in one or more deployment targets.
- Enable Dry Run (check mode - no changes applied) to validate connectivity and configuration without making changes. This is strongly recommended for the first deployment to any new host.
- Click Preview Config to view the generated probe configuration (rendered from the Config Template) in the Config Preview panel on the right.
- Click Test Deploy (in dry run mode) or Deploy to execute.
The deployment process connects to the target host via SSH, copies the probe binary, renders and deploys the configuration file, installs optional packages (SNMP tools, traceroute, WireGuard), and starts the probe service.
Click Preview Config before deploying to verify the generated config.yaml is correct. This shows exactly what configuration the probe will receive, including the API endpoint, probe identity, capture settings, and IPFIX export parameters.
Upgrade Probes
The Upgrade Probes tab allows you to push the latest probe binary to existing deployed probes.
Probe Selection
All deployed probes are displayed as cards showing:
- Probe name — The probe's friendly name.
- IP address — The probe's management IP.
- Site — The assigned site.
- Auth status — Green indicator with "✓ Password auth" or "✓ Key auth" if credentials are configured. Red indicator with "Missing SSH credentials" if credentials are not set.
Use Select All to select every probe, or check individual probes to upgrade specific ones. Probes with missing SSH credentials cannot be upgraded until credentials are configured under Settings → Devices.
Upgrading
- Select the probes to upgrade.
- Enable Dry Run to validate connectivity without applying changes.
- Click Upgrade N Probe(s) to push the latest binary to the selected probes.
The upgrade process connects to each probe via SSH, stops the probe service, replaces the binary, and restarts the service. The probe's existing configuration is preserved.
Job History
The Job History tab shows a log of all deployment and upgrade operations, including:
- Job type (deploy or upgrade).
- Target devices.
- Timestamp.
- Success/failure status per device.
- Ansible output for troubleshooting failed deployments.
Config Template
The Config Template tab displays and manages the Jinja2 template used to generate probe config.yaml files. This template is rendered at deployment time with probe-specific variables to produce the final configuration for each probe.
Available Variables
Variables are organized into three categories:
API / Identity
| Variable | Description |
|---|---|
api_endpoint | The URL of the WhiteOwl central API server that the probe registers with. |
probe_name | The probe's friendly name as configured during deployment. |
site_name | The site name the probe is assigned to. |
site_id | The numeric site ID (overrides site_name if set). |
sampler_address | The IP address used as the probe's sampler/exporter address in flow records. |
Capture
| Variable | Description |
|---|---|
capture_interface | The network interface to capture packets on (e.g., eth0, any). |
capture_promiscuous | Whether to enable promiscuous mode on the capture interface. |
capture_snap_len | The snapshot length (bytes) for packet capture. |
capture_buffer_size_mb | The kernel ring buffer size in MB for packet capture. |
bpf_filter | An optional BPF (Berkeley Packet Filter) expression to limit captured traffic. |
IPFIX Export
| Variable | Description |
|---|---|
collector_ip | The IP address of the WhiteOwl flow collector to send IPFIX records to. |
collector_port | The UDP port for IPFIX export (default: 4739). |
domain_id | The IPFIX observation domain ID. |
active_timeout | The active flow timeout in seconds — how long a flow can remain active before being exported. |
inactive_timeout | The inactive flow timeout in seconds — how long a flow must be idle before being exported. |
Editing the Template
Click Edit Template to modify the Jinja2 template. The template generates a YAML configuration file that includes sections for API registration, probe identity, capture settings, and IPFIX export. Changes to the template apply to all future deployments — existing probes are not affected until they are redeployed or their configuration is manually updated.
Full Configuration Reference
Below is the complete config.yaml generated by the template, with all available sections and parameters documented.
API Registration
Controls how the probe communicates with the WhiteOwl central server.
api:
endpoint: "http://192.168.100.132:3001"
timeout: 30
skip_verify: true
# ca_cert: "/etc/ssl/certs/chompy-ca.crt"
| Parameter | Description | Default |
|---|---|---|
endpoint | The URL of the WhiteOwl backend API. The probe registers itself and polls for synthetic test assignments via this endpoint. | Required |
timeout | Request timeout in seconds for API calls. | 30 |
skip_verify | Skip TLS certificate verification. Set to true when using self-signed certificates. | true |
ca_cert | Path to a CA certificate file for TLS verification. Uncomment and set if using a custom CA instead of skip_verify. | — |
Probe Identity
Defines the probe's identity and how it appears in WhiteOwl.
probe:
name: "probe-192-168-100-132"
site_name: "HQ Data Center"
site_id: 1
device_type: "probe"
role: "packet-capture"
sampler_address: "192.168.100.132"
snmp_enabled: true
snmp_credential_id: 0
| Parameter | Description | Default |
|---|---|---|
name | The probe's friendly name. This appears throughout WhiteOwl in device lists, topology, and dashboards. | Set during deployment |
site_name | The site this probe belongs to. Used for site-level grouping and filtering. | Set during deployment |
site_id | Numeric site ID. If set, overrides site_name for site assignment. | — |
device_type | The device type reported to WhiteOwl. | probe |
role | The device role reported to WhiteOwl. | packet-capture |
sampler_address | The IP address used as the sampler/exporter address in flow records. This is how WhiteOwl identifies which probe generated a flow. | Probe's management IP |
snmp_enabled | Whether to enable SNMP polling of the probe host itself (CPU, memory, disk). | true |
snmp_credential_id | The SNMP credential ID to use for polling this probe. Set to 0 for auto-match by subnet. | 0 |
Feature Toggles
Enable or disable major probe capabilities.
features:
packet_capture: true
synthetics: true
dpi: true
| Parameter | Description | Default |
|---|---|---|
packet_capture | Enable packet capture and IPFIX flow export. When disabled, the probe does not capture any traffic. | true |
synthetics | Enable synthetic test execution. When enabled, the probe polls the API for assigned ping, HTTP, DNS, and traceroute tests. | true |
dpi | Enable nDPI 5.0 library for deep packet inspection capabilities. Over 486 applications are identified. | true |
Packet Capture
Configures the probe's packet capture engine.
capture:
interface: "eth0"
promiscuous: true
snap_len: 1500
buffer_size_mb: 64
bpf_filter: ""
capture_sni: true
| Parameter | Description | Default |
|---|---|---|
interface | The network interface to capture packets on (e.g., eth0, ens192, wlo1). Set to any to capture on all interfaces. | Set during deployment |
promiscuous | Enable promiscuous mode, allowing the probe to see all traffic on the segment — not just traffic addressed to the probe's MAC. Required for accurate traffic monitoring. | true |
snap_len | Snapshot length in bytes — how much of each packet to capture. 1500 captures full Ethernet frames. Lower values reduce memory usage but may miss payload data needed for application detection. | 1500 |
buffer_size_mb | Kernel ring buffer size in MB. Larger buffers reduce packet drops under high traffic loads. Increase this on high-throughput links. | 64 |
bpf_filter | A BPF (Berkeley Packet Filter) expression to limit which packets are captured. Leave empty to capture all traffic. Example: not port 22 to exclude SSH traffic, or net 10.0.0.0/8 to capture only RFC 1918 traffic. | "" (all traffic) |
capture_sni | Extract Server Name Indication (SNI) from TLS and QUIC handshakes. Enables application-level visibility (e.g., identifying google.com, slack.com) without decrypting traffic. | true |
IPFIX Export
Configures how the probe exports flow records to the WhiteOwl collector.
export:
collector_ip: "192.168.100.132"
collector_port: 2055
domain_id: 1
template_id: 256
template_interval: 30s
interface_index: 0
active_timeout: 60s
inactive_timeout: 15s
track_tcp_performance: true
| Parameter | Description | Default |
|---|---|---|
collector_ip | The IP address of the WhiteOwl flow collector to send IPFIX records to. Typically the WhiteOwl central server. | WhiteOwl server IP |
collector_port | The UDP port for IPFIX export. | 2055 |
domain_id | The IPFIX observation domain ID. Use different IDs to distinguish flows from multiple probes when they arrive at the same collector. | 1 |
template_id | The IPFIX template ID used in exported records. | 256 |
template_interval | How often to re-send the IPFIX template to the collector. Templates define the structure of flow records. | 30s |
interface_index | The SNMP interface index to report in IPFIX records. Set to 0 for auto-detection. | 0 |
active_timeout | Active flow timeout — the maximum duration a flow can remain active before being exported. Longer timeouts produce fewer, larger flow records. | 60s |
inactive_timeout | Inactive flow timeout — how long a flow must be idle before it is considered complete and exported. | 15s |
track_tcp_performance | Track TCP performance metrics including round-trip time (RTT), retransmits, and window size. These metrics are included in exported flow records and available in Flow Explorer and dashboards. | true |
Synthetic Tests
Configures the synthetic testing engine (when features.synthetics is enabled).
synthetics:
poll_interval: 30s
max_concurrent_tests: 5
| Parameter | Description | Default |
|---|---|---|
poll_interval | How often the probe polls the WhiteOwl API for assigned synthetic test definitions. | 30s |
max_concurrent_tests | Maximum number of synthetic tests to execute simultaneously. Increase for probes with many assigned tests; decrease on resource-constrained hosts. | 5 |
Environment Variable Overrides
Every configuration parameter can be overridden via environment variables on the probe host. This is useful for containerized deployments or when you need to change a setting without modifying the config file.
| Section | Variables |
|---|---|
| API | API_ENDPOINT, API_TIMEOUT, API_SKIP_VERIFY, API_CA_CERT |
| Probe | PROBE_NAME, PROBE_SITE_NAME, PROBE_SITE_ID, PROBE_DEVICE_TYPE, PROBE_ROLE, PROBE_SAMPLER_ADDRESS, PROBE_SNMP_ENABLED, PROBE_SNMP_CREDENTIAL_ID |
| Features | FEATURE_PACKET_CAPTURE, FEATURE_SYNTHETICS |
| Capture | CAPTURE_INTERFACE, CAPTURE_PROMISCUOUS, CAPTURE_SNAP_LEN, CAPTURE_BUFFER_SIZE_MB, CAPTURE_BPF_FILTER, CAPTURE_SNI |
| Export | IPFIX_COLLECTOR, IPFIX_PORT, IPFIX_DOMAIN_ID, IPFIX_TEMPLATE_ID, IPFIX_INTERFACE_INDEX, IPFIX_ACTIVE_TIMEOUT, IPFIX_INACTIVE_TIMEOUT, IPFIX_TRACK_TCP_PERFORMANCE |
| Synthetics | SYNTHETICS_POLL_INTERVAL, SYNTHETICS_MAX_CONCURRENT |
Environment variables take precedence over values in config.yaml.
Config Backups
The Config Backups tab provides a searchable archive of probe configurations backed up from deployed probes.
Probe List
The left panel lists all probes with:
- Probe name and IP — The probe identity.
- Site — The assigned site.
- Backup count — How many configuration backups are stored for this probe (e.g.,
1 backup,0 backups).
Use the search bar to filter probes by name or IP address. Click a probe to expand its backup history and see timestamped entries.
Config Viewer
Selecting a backup opens the Config Viewer on the right, displaying:
- Probe name — Which probe this configuration belongs to.
- Timestamp — When the backup was taken.
- Full configuration — The complete
config.yamlwith syntax highlighting, showing all sections: API registration, probe identity, site assignment, capture settings, and IPFIX export parameters.
Click Download to save the configuration file locally. Click the 🗑️ icon to delete a backup.
VPN Setup
The VPN Setup tab configures a WireGuard VPN server on the WhiteOwl central server, enabling secure tunnels between the central server and probes deployed on remote or NAT'd networks.
WireGuard VPN Server
Displays the server-side VPN configuration:
| Field | Description |
|---|---|
| Status | Whether the VPN server is configured and active (e.g., "VPN Server Configured" with green checkmark). |
| Endpoint | The public IP address or hostname that probes will connect to. This must be reachable from the remote probe networks. |
| Port | The WireGuard UDP listen port (default: 51820). This port must be open on any firewalls between probes and the server. |
| Server IP | The VPN tunnel IP address of the server (e.g., 10.10.0.1). |
| Server Public Key | The WireGuard public key for the server. Probes use this to authenticate the tunnel. |
Click Re-apply Server Config to regenerate and reload the WireGuard server configuration (e.g., after adding new peers).
VPN Peers
Lists all probes configured as WireGuard peers. Probes are automatically added as VPN peers when deployed with the WireGuard VPN checkbox enabled. Each peer is assigned a unique VPN IP address from the 10.10.0.0/24 subnet.
If no probes have been deployed with VPN enabled, the panel displays: "No VPN peers configured. Deploy a probe with 'Enable WireGuard VPN' checked."
Live Status
Shows the current operational status of the WireGuard interface:
- active — The WireGuard tunnel is running and the interface is up.
- not active — The WireGuard interface is down or not configured.
VPN Requirements
To use the WireGuard VPN feature:
- WireGuard must be installed on the WhiteOwl central server (
apt install wireguardor equivalent). - UDP port 51820 must be open and forwarded to the WhiteOwl server if behind NAT.
- The server endpoint must be set to a public IP or hostname reachable from remote probe locations.
- The VPN server must be initialized via the VPN Setup tab before deploying VPN-enabled probes.
WireGuard VPN is primarily useful when deploying probes to cloud instances (AWS, Azure, GCP) or remote offices where the probe cannot directly reach the WhiteOwl central server. The VPN creates a secure tunnel so the probe can register with the API, export flow data, and receive management commands regardless of NAT or firewall restrictions.