CLI Reference¶
Complete reference for all NetTap shell scripts and their options.
Installation Scripts¶
scripts/install/install.sh¶
Main installation script. Orchestrates the full deployment: pre-flight checks, system dependencies, network bridge, Malcolm stack, systemd services, mDNS, and verification.
| Option | Description |
|---|---|
--skip-bridge |
Skip bridge configuration (if already done) |
--skip-pull |
Skip Docker image pull (use cached images) |
--skip-malcolm |
Skip Malcolm deployment entirely (bridge + deps only) |
--no-persist-bridge |
Don't write persistent netplan config (runtime-only bridge) |
--dry-run |
Log all actions without executing them |
-v, --verbose |
Enable debug output |
-h, --help |
Show help |
Steps executed:
- Pre-flight checks (root, OS, architecture, hardware validation)
- System dependencies (Docker, bridge-utils, net-tools, Python, Avahi)
- Kernel tuning (vm.max_map_count, network buffers, conntrack)
- Network bridge (br0 with WAN + LAN NICs)
- Malcolm deployment (container images, TLS certs, auth)
- Systemd services (nettap.service)
- mDNS configuration (Avahi)
- Firewall rules (UFW, if active)
- Post-install verification
scripts/install/validate-hardware.sh¶
Hardware validation. Checks CPU, RAM, disk, and NIC count against minimum requirements.
Can be sourced (provides validate_hardware function) or run standalone:
Exit codes:
| Code | Meaning |
|---|---|
0 |
All checks passed |
1 |
Warnings (e.g., below recommended but above minimum) |
2 |
Hard failure (does not meet minimum requirements) |
Thresholds:
| Check | Minimum | Recommended |
|---|---|---|
| CPU cores | 2 | 4 |
| RAM | 8 GB (~7500 MB) | 16 GB (~15000 MB) |
| Disk | 512 GB (~400 GB formatted) | 1 TB |
| NICs | 2 physical | 3 (including management) |
scripts/install/deploy-malcolm.sh¶
Deploy the Malcolm container stack. Pulls images, generates TLS certificates, and configures authentication.
| Option | Description |
|---|---|
--skip-pull |
Skip Docker image pull |
--dry-run |
Log without executing |
-v, --verbose |
Debug output |
scripts/install/malcolm-config.sh¶
Generate Malcolm configuration files and environment settings.
scripts/install/setup-watchdog.sh¶
Install and configure the hardware watchdog timer.
Deploys config/watchdog/watchdog.conf to /etc/watchdog.conf and enables the watchdog service.
scripts/install/setup-firewall.sh¶
Configure UFW firewall rules for NetTap.
Bridge Scripts¶
scripts/bridge/setup-bridge.sh¶
Create, validate, or tear down the transparent network bridge.
| Option | Description |
|---|---|
--wan <iface> |
WAN-side interface (default: $WAN_INTERFACE or eth0) |
--lan <iface> |
LAN-side interface (default: $LAN_INTERFACE or eth1) |
--mgmt <iface> |
Management interface for dashboard access |
--persist |
Write netplan config and systemd units for boot persistence |
--no-persist |
Skip persistence (runtime only, for testing) |
--validate-only |
Check existing bridge config without making changes |
--teardown |
Remove bridge and restore interfaces to original state |
--detect |
Auto-detect NICs and suggest WAN/LAN assignment |
--dry-run |
Log commands without executing |
-v, --verbose |
Debug output |
-h, --help |
Show help |
Modes:
Creates br0, adds NICs, tunes offloads, enables promiscuous mode, and optionally writes netplan config for persistence.
Checks bridge exists, is UP, STP disabled, interfaces attached, promiscuous mode on, forward delay 0.
Removes bridge, restores interfaces, cleans up netplan config, systemd units, and sysctl settings.
scripts/bridge/bypass-mode.sh¶
Enable or disable bridge bypass mode (for maintenance or troubleshooting).
scripts/bridge/harden-bridge.sh¶
Apply additional bridge hardening settings.
Utility Scripts¶
scripts/generate-secrets.sh¶
Generate cryptographically random passwords and secrets for deployment.
| Option | Description |
|---|---|
--stdout |
Print secrets to stdout instead of writing to .env |
--env-file PATH |
Write to a custom .env path (default: /opt/nettap/.env) |
--force |
Regenerate all secrets even if they already exist |
--dry-run |
Show what would be done without writing |
-v, --verbose |
Debug output |
-h, --help |
Show help |
Generates OPENSEARCH_ADMIN_PASSWORD, GRAFANA_ADMIN_PASSWORD, JWT_SECRET and API_KEY_SALT. ARKIME_SECRET, which compose still requires even with Arkime off, is written to docker/.env by scripts/install/malcolm-config.sh.
scripts/generate-cert.sh¶
Generate a self-signed TLS certificate for the NetTap dashboard.
Outputs docker/ssl/nettap.crt and docker/ssl/nettap.key.
scripts/common.sh¶
Shared shell utilities sourced by all other scripts. Provides:
- Logging:
log,warn,error,debugfunctions - Dry-run support:
runfunction wraps commands for--dry-runmode - Cleanup traps:
push_cleanup,enable_cleanup_trap,disable_cleanup_trap - Lock files:
acquire_lock,release_lock(prevents concurrent script execution) - Retry logic:
retry <attempts> <delay> <command>for transient failures - System checks:
require_root,check_ubuntu,check_arch,check_interface_exists,check_command - Environment loading:
load_envreads.envfiles - Network helpers:
list_physical_nics,get_nic_driver,nic_has_carrier,get_nic_speed,get_nic_mac
Service Management¶
These are systemd commands, not NetTap scripts, but they are the primary way to manage the running system:
# Start NetTap
sudo systemctl start nettap
# Stop NetTap
sudo systemctl stop nettap
# Restart NetTap
sudo systemctl restart nettap
# Check status
systemctl status nettap
# View logs
journalctl -u nettap -f
# Enable/disable auto-start on boot
sudo systemctl enable nettap
sudo systemctl disable nettap
Docker Compose Commands¶
# Check container status
docker compose -f /opt/nettap/docker/docker-compose.yml ps
# View logs for a specific container
docker compose -f /opt/nettap/docker/docker-compose.yml logs -f zeek-live
# Restart a specific container
docker compose -f /opt/nettap/docker/docker-compose.yml restart suricata-live
# Pull updated images
docker compose -f /opt/nettap/docker/docker-compose.yml pull
# Rebuild custom images
docker compose -f /opt/nettap/docker/docker-compose.yml build