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=