Skip to content

Environment Variable Reference

Complete reference for all environment variables used by NetTap. Set these in /opt/nettap/.env.


Network Interfaces

Variable Default Description
WAN_INTERFACE eth0 Network interface connected to the ISP modem
LAN_INTERFACE eth1 Network interface connected to the router
MGMT_INTERFACE (none) Management interface for dashboard access
MGMT_IP (none) Static IP address for the management interface
MGMT_NETMASK 255.255.255.0 Netmask for the management interface

Dashboard

Variable Default Description
NETTAP_HOSTNAME nettap.local mDNS hostname for the appliance
DASHBOARD_PORT 443 HTTPS port for the NetTap dashboard

OpenSearch

Variable Default Description
OPENSEARCH_JAVA_OPTS -Xms4g -Xmx4g JVM heap size for OpenSearch. Set -Xms and -Xmx to the same value.
OPENSEARCH_ADMIN_PASSWORD N3tT@p_0p3n Initial admin password for OpenSearch. Auto-generated by generate-secrets.sh.
OPENSEARCH_URL https://opensearch:9200 Internal OpenSearch URL (used by containers).

Storage Retention

Variable Default Description
RETENTION_HOT 90 Days to retain Zeek metadata logs (hot tier)
RETENTION_WARM 180 Days to retain Suricata alert data (warm tier)
RETENTION_COLD 30 Days to retain raw PCAP captures (cold tier)
DISK_THRESHOLD_PERCENT 80 Start pruning old data when disk usage exceeds this percentage
EMERGENCY_THRESHOLD_PERCENT 90 Aggressive pruning threshold

Daemon

Variable Default Description
API_PORT 8880 Port for the daemon's HTTP API server
STORAGE_CHECK_INTERVAL 300 Seconds between storage maintenance cycles
SMART_CHECK_INTERVAL 3600 Seconds between SMART health checks
SMART_DEVICE /dev/nvme0n1 Block device to monitor for SMART health
LOG_LEVEL INFO Daemon log level: DEBUG, INFO, WARNING, ERROR
LAN_SUBNETS (empty) Your LAN subnets, comma-separated (/8, /16 or /24), e.g. 192.168.1.0/24,10.10.0.0/24. Empty: the daemon detects them at start from outbound traffic, keeping every private /24 with at least 1% of it. Devices, Live Monitor, risk and bandwidth count only devices in these subnets

Alerting / Notifications

Variable Default Description
SMTP_HOST (none) SMTP server address for email notifications
SMTP_PORT 587 SMTP port
SMTP_USER (none) SMTP authentication username
SMTP_PASS (none) SMTP authentication password
ALERT_EMAIL (none) Email address to receive alert notifications
WEBHOOK_URL (none) Webhook URL for alert notifications (Slack, Discord, etc.)

Malcolm Stack

Variable Default Description
MALCOLM_IMAGE_REGISTRY ghcr.io/idaholab/malcolm Docker registry for Malcolm images
MALCOLM_IMAGE_TAG 26.02.0 Malcolm container image tag
MALCOLM_HTTPS_PORT 9443 HTTPS port for Malcolm dashboards
MALCOLM_CERTS_DIR ./certs Directory containing Malcolm TLS certificates
MALCOLM_AUTH_DIR ./auth Directory containing Malcolm authentication files

Capture

Variable Default Description
PCAP_IFACE br0 Network interface for packet capture
PCAP_ROTATE_MB 100 (the installer writes 256 to docker/.env) Rotate PCAP files at this size (MB); PCAP Search can't read files over ~700 MB
PCAP_ROTATE_MIN 10 Rotate PCAP files at this interval (minutes)
PCAP_DIR /opt/nettap/pcap Directory for PCAP file storage
ZEEK_LOCAL_NETS 192.168.0.0/16,10.0.0.0/8,172.16.0.0/12 RFC 1918 local network definitions for Zeek

Suricata rules

Set in docker/docker-compose.yml for suricata-live (NET-191). Malcolm's updater reads them at every update.

Variable Default Description
SURICATA_UPDATE_ENABLE_SOURCES et/open,abuse.ch/sslbl-blacklist,echap/stalkerware,ipfire/dbl The rule sources, comma-separated. Each start enables exactly these (stored source configs are wiped first). With an ET Pro code saved, et/open becomes et/pro at start.
SURICATA_DISABLE_SIDS 2200121,2231001,re:msg:"IPFire DBL \[(?!Malware\]\|Phishing\]) Lines for /etc/suricata/disable.conf: two decoder rules that fire on switch traffic, and the IPFire DBL allowlist (every category except Malware and Phishing off).
SURICATA_UPDATE_RULES true Update rules at start, nightly at 00:00 UTC and on "Update now".
SURICATA_UPDATE_ETOPEN removed Unused by Malcolm 26.10.0; upstream would add ET Open beside ET Pro. ET Open is chosen through the source list.

ET Pro code

Not an environment variable in .env. Settings › Suricata rules writes /etc/nettap/suricata.env (root, mode 600) with one line, SURICATA_ETPRO_CODE=<16-64 letters and digits>. config/capture/nettap-capture-env.sh reads it when suricata-live starts; an invalid value is ignored without being printed. The old SURICATA_ET_PRO_KEY API key field is retired.

Rule update wrapper (config/suricata/nettap-rules-update.sh)

State lives on the nettap-rules-state volume (/run/nettap-rules in suricata-live, /var/run/nettap-rules in the daemon): rules.lock, update-status.json, update-in-progress, last-good and its gen-* copies. The overrides below exist for tests.

Variable Default Description
NETTAP_RULES_STATE /run/nettap-rules State directory (the daemon reads the same variable)
NETTAP_RULES_LOCK_WAIT 900 Seconds an update waits for the rules lock
NETTAP_RULES_RELOAD_WAIT 300 Seconds to wait for Suricata to load new or restored rules
NETTAP_RULES_RETRY_S 5 Seconds between reload checks
NETTAP_RULES_UPDATE_MAX 900 Seconds Malcolm's updater may run before it is stopped (so it can't hold the rules lock)
NETTAP_MALCOLM_UPDATE /usr/local/bin/malcolm-suricata-update-rules.sh Malcolm's updater, kept beside the shim
NETTAP_RULES_SOURCES_FILE /var/lib/suricata/update/nettap-enable-sources The source list the container started with (for docker exec updates)
NETTAP_SURICATA_SOCKET /var/run/suricata/suricata-command.socket Suricata's command socket
NETTAP_SURICATA_ENV /etc/nettap/suricata.env Where the loader and the daemon find the ET Pro code

Own rules (daemon, NET-191 slice 3)

owner.rules lives on the suricata-custom-rules volume: rw in the daemon, ro in suricata-live at /opt/suricata/rules/custom (Malcolm lists SURICATA_CUSTOM_RULES_DIR/**/*.rules in rule-files at start). Suricata's test of a save runs on snapshots in the nettap-rules-staging volume, which suricata-live never mounts. The limits (2,000 rules, 256 KB) are constants in daemon/services/owner_rules_validator.py. The overrides below exist for tests.

Variable Default Description
NETTAP_CUSTOM_RULES_DIR /var/lib/nettap-suricata-custom The daemon's mount of suricata-custom-rules
NETTAP_RULES_STAGING_DIR /var/lib/nettap-rules-staging The daemon's mount of nettap-rules-staging; must not be inside the custom rules dir

The test container mounts the staging volume from the host, so the daemon inspects its own container for the volume's host path. That container's name is DAEMON_CONTAINER_NAME, the variable the Malcolm update already uses.


Logstash

Variable Default Description
LS_JAVA_OPTS -Xmx2g -Xms2g JVM heap size for Logstash
LOGSTASH_WORKERS 2 Number of Logstash pipeline workers

Arkime

Arkime is off by default (compose profile arkime) and is not part of the running stack. Its ARKIME_SECRET must still be set because compose interpolates every service's variables.


Redis

Variable Default Description
REDIS_PASSWORD NetTap_Redis_Secret Redis authentication password. Auto-generated by generate-secrets.sh.

Grafana

Variable Default Description
GRAFANA_ADMIN_PASSWORD nettap Grafana admin password. Auto-generated by generate-secrets.sh.

Nginx

Variable Default Description
NGINX_AUTH_MODE basic Malcolm nginx authentication mode

Process Identity

Variable Default Description
PUID 1000 User ID for container processes
PGID 1000 Group ID for container processes

Bridge Health Monitoring

Variable Default Description
BRIDGE_NAME br0 Name of the network bridge
WAN_IFACE eth0 WAN-side interface in the bridge
LAN_IFACE eth1 LAN-side interface in the bridge

Software Updates

Variable Default Description
COMPOSE_FILE /opt/nettap/docker/docker-compose.yml Path to Docker Compose file
BACKUP_DIR /opt/nettap/backups Directory for update backups
GITHUB_REPO EliasMarine/NetTap GitHub repository for update checks

Data Paths

Variable Default Description
GEOIP_DB_PATH /opt/nettap/data/GeoLite2-City.mmdb Path to MaxMind GeoIP database
DEVICE_BASELINE_FILE /opt/nettap/data/device_baseline.json Device baseline storage file
INVESTIGATIONS_FILE /opt/nettap/data/investigations.json Investigation bookmarks storage
DETECTION_PACKS_DIR /opt/nettap/data/detection-packs Directory for community detection packs
REPORTS_DIR /opt/nettap/data/reports Directory for generated reports
REPORT_SCHEDULES_FILE /opt/nettap/data/report_schedules.json Report schedule configuration
NETTAP_ENV_FILE /opt/nettap/.env Path to the main environment file

Example .env File

.env
# NetTap Environment Configuration

# Network interfaces
WAN_INTERFACE=eth0
LAN_INTERFACE=eth1
MGMT_INTERFACE=eth2
MGMT_IP=192.168.1.100
MGMT_NETMASK=255.255.255.0

# Dashboard
NETTAP_HOSTNAME=nettap.local
DASHBOARD_PORT=443

# OpenSearch
OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g"

# Storage retention (days)
RETENTION_HOT=90
RETENTION_WARM=180
RETENTION_COLD=30
DISK_THRESHOLD_PERCENT=80

# Alerting (optional)
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=
ALERT_EMAIL=

WEBHOOK_URL=