Skip to content
1337skills 1337skills

darkstat

Installation

Ubuntu/Debian

sudo apt-get update
sudo apt-get install darkstat

CentOS/RHEL

sudo yum install darkstat

From Source

cd /tmp
wget https://github.com/emikulic/darkstat/releases/download/3.5.20/darkstat-3.5.20.tar.gz
tar xzf darkstat-3.5.20.tar.gz
cd darkstat-3.5.20
./configure
make
sudo make install

macOS (Homebrew)

brew install darkstat

Verify Installation

darkstat --version
darkstat --help

Basic Usage

Start Capturing on Default Interface

# Start with default settings (localhost:666)
sudo darkstat -i eth0

# Start on specific interface
sudo darkstat -i wlan0

Access Web Dashboard

  • Open browser: http://localhost:666
  • Real-time traffic statistics
  • Bandwidth usage graphs
  • Top hosts and protocols
  • DNS resolution names

Stop Capture

# Press Ctrl+C in terminal
# Or kill process
sudo pkill darkstat

Interface Selection

List Available Interfaces

# Show all network interfaces
ip link show

# Or use ifconfig
ifconfig

# Or with darkstat
sudo darkstat -l

Common Interface Names

InterfaceTypeExample Use
eth0EthernetWired connection
wlan0WiFiWireless connection
docker0VirtualDocker network
veth*VirtualContainer interface
tun0VPNVPN tunnel

Monitor Multiple Interfaces

# Start separate instances on different ports
sudo darkstat -i eth0 -p 666
sudo darkstat -i wlan0 -p 667

Promiscuous Mode

# Enable promiscuous mode (captures all traffic)
sudo darkstat -i eth0 -m

# Monitor mode on wireless
sudo darkstat -i wlan0 -m

Web Dashboard

Main Dashboard Features

SectionPurpose
BandwidthReal-time and historical traffic
Top HostsMost active IP addresses
ProtocolsTraffic breakdown by protocol
PortsConnection ports and protocols
DNSResolved hostnames

Dashboard Navigation

  1. Graph - Real-time bandwidth graph
  2. Hosts - Connected IP addresses
  3. Ports - TCP/UDP port activity
  4. Protocols - IP, TCP, UDP, ICMP breakdown
  5. Export - Save data as CSV

Real-time Monitoring

  • Bandwidth graph updates every second
  • Color-coded incoming/outgoing traffic
  • Historical data retention configurable
  • Peak and average rates shown

Filtering Traffic

Filter by IP Address

# Only monitor traffic to/from specific IP
sudo darkstat -i eth0 -f "host 192.168.1.100"

# Exclude IP address
sudo darkstat -i eth0 -f "not host 192.168.1.1"

Filter by Network

# Monitor specific subnet only
sudo darkstat -i eth0 -f "net 192.168.1.0/24"

# Exclude local traffic
sudo darkstat -i eth0 -f "not net 192.168.0.0/16"

Filter by Port

# Monitor specific port
sudo darkstat -i eth0 -f "port 80"

# Monitor port range
sudo darkstat -i eth0 -f "port 80 or port 443"

# Exclude common ports
sudo darkstat -i eth0 -f "not (port 22 or port 23)"

Filter by Protocol

# Monitor TCP traffic only
sudo darkstat -i eth0 -f "tcp"

# Monitor UDP traffic only
sudo darkstat -i eth0 -f "udp"

# Monitor ICMP (ping)
sudo darkstat -i eth0 -f "icmp"

Complex Filters

# Multiple conditions (AND)
sudo darkstat -i eth0 -f "tcp and port 443"

# Multiple conditions (OR)
sudo darkstat -i eth0 -f "tcp port 80 or tcp port 443"

# Exclude and include
sudo darkstat -i eth0 -f "tcp and not port 22"

DNS Resolution

Enable DNS Resolution

# Resolve hostnames (enabled by default)
sudo darkstat -i eth0 -b

# Bind to address (localhost)
sudo darkstat -i eth0 -b 127.0.0.1

View Resolved Names

  1. Open dashboard
  2. Click Hosts tab
  3. Hostnames shown if DNS resolution succeeds
  4. IP addresses shown if resolution fails

Control DNS Settings

SettingDescription
DNS cacheStores resolved names
Reverse lookupConvert IP to hostname
Local hosts/etc/hosts file usage
TimeoutDNS query timeout (default 2s)

Manual DNS Lookup

# Resolve IP from command line
nslookup 192.168.1.100
dig -x 192.168.1.100

Database Management

Data Storage Location

# Default database directory
~/.darkstat/

# Database file
~/.darkstat/darkstat.db

# Check size
du -h ~/.darkstat/darkstat.db

Export Data as CSV

  1. Open dashboard
  2. Click Export button
  3. Select data type (Hosts, Protocols, Ports)
  4. Save CSV file

Export via Command Line

# No direct CLI export, but redirect browser download
# Or use sqlite3 to access database directly
sqlite3 ~/.darkstat/darkstat.db ".dump" > backup.sql

Backup Database

# Create backup
cp -r ~/.darkstat/ ~/.darkstat.backup

# Or archive
tar czf darkstat-backup.tar.gz ~/.darkstat/

Clear Database

# Stop darkstat
sudo pkill darkstat

# Remove database
rm -rf ~/.darkstat/

# Restart darkstat
sudo darkstat -i eth0

Database Size Management

# Check database size
ls -lh ~/.darkstat/darkstat.db

# Vacuum (optimize) database
sqlite3 ~/.darkstat/darkstat.db "VACUUM;"

# Check database integrity
sqlite3 ~/.darkstat/darkstat.db "PRAGMA integrity_check;"

Running as Daemon

Start as System Service

# Start darkstat service
sudo systemctl start darkstat

# Enable on boot
sudo systemctl enable darkstat

# Check status
sudo systemctl status darkstat

# Stop service
sudo systemctl stop darkstat

Edit Service Configuration

# Create config file
sudo nano /etc/darkstat/init.cfg

# Example configuration
INTERFACE="eth0"
PORT="666"
BINDADDR="0.0.0.0"
QUERYINTERFACE="yes"
LOGFILE="/var/log/darkstat.log"

Daemon Mode from Command Line

# Run in background
sudo darkstat -i eth0 -d

# Specify PID file
sudo darkstat -i eth0 -d -p /var/run/darkstat.pid

# Log output
sudo darkstat -i eth0 -d 2>&1 | tee darkstat.log

Check Running Process

# View darkstat processes
ps aux | grep darkstat

# Check port listening
sudo netstat -lntp | grep 666
sudo ss -lntp | grep 666

Configuration Options

Command Line Parameters

# Specify interface and port
sudo darkstat -i eth0 -p 8080

# Bind to specific address
sudo darkstat -i eth0 -b 192.168.1.10

# Filter expression
sudo darkstat -i eth0 -f "tcp port 80"

# Verbose logging
sudo darkstat -i eth0 -v

# Daemonize
sudo darkstat -i eth0 -d

# Chroot (security)
sudo darkstat -i eth0 -c /var/darkstat

Configuration File

# Create /etc/darkstat/init.cfg
INTERFACE="eth0"
PORT="666"
BINDADDR="127.0.0.1"
QUERYINTERFACE="yes"
LOGFILE="/var/log/darkstat.log"
HISTORYLEN="50"
SYSLOG="no"
PCAP_BUFSIZE="0"
BANNER="yes"
OptionDefaultDescription
INTERFACEeth0Network interface to monitor
PORT666Web dashboard port
BINDADDRlocalhostIP address to bind to
QUERYINTERFACEyesEnable interface info queries
HISTORYLEN50History length in entries
BANNERyesShow darkstat banner

Common Monitoring Scenarios

Scenario: Monitor Internet Bandwidth Usage

# 1. Start darkstat on WAN interface
sudo darkstat -i eth0

# 2. Open http://localhost:666
# 3. View Bandwidth graph for total usage
# 4. Check Hosts tab for top consumers
# 5. Monitor historical data

Scenario: Track Specific Server Traffic

# 1. Filter traffic to server
sudo darkstat -i eth0 -f "host 192.168.1.50"

# 2. Open dashboard
# 3. Monitor Ports tab for active services
# 4. View Protocols breakdown
# 5. Track connection patterns

Scenario: Monitor WiFi Client Usage

# 1. Start on WiFi interface
sudo darkstat -i wlan0 -m

# 2. Resolve client hostnames
# 3. View Top Hosts
# 4. Identify heavy users
# 5. Check bandwidth per client

Scenario: Export Daily Statistics

# 1. Let darkstat run overnight
sudo darkstat -i eth0 -d

# 2. Next morning, open dashboard
# 3. Click Export
# 4. Save CSV file
# 5. Analyze with spreadsheet tool

Scenario: Monitor VPN Traffic

# 1. Start on VPN interface
sudo darkstat -i tun0

# 2. Monitor traffic through tunnel
# 3. View Protocol breakdown
# 4. Track VPN throughput
# 5. Identify data leaks

Comparison with Other Tools

darkstat vs ntopng

Featuredarkstatntopng
SizeLightweightHeavy
SetupSimpleComplex
Web UIBasicAdvanced
Resource UsageLowHigh
GeolocationNoYes
AlertsLimitedYes
CostFreeFree/Paid
Learning CurveEasyMedium

darkstat vs iftop

Featuredarkstatiftop
InterfaceWebTerminal
StorageDatabaseNone
HistoryYesReal-time only
BandwidthReal-timeReal-time
Drill-downYesLimited
ExportYesNo
ProtocolsTCP/UDPLayer 3/4

darkstat vs vnstat

Featuredarkstatvnstat
Protocol DetailYesNo
Real-timeYesInterval
Web UIYesNo
DatabaseSQLiteCustom
PortabilityGoodGood
Install SizeSmallSmall
Use CaseReal-time analysisLong-term stats

Troubleshooting

Dashboard Not Loading

# Check if darkstat is running
sudo ps aux | grep darkstat

# Verify port is listening
sudo netstat -lntp | grep 666

# Check firewall rules
sudo ufw status
sudo firewall-cmd --list-ports

No Traffic Data Showing

# Verify correct interface
ip link show

# Check filter syntax
sudo darkstat -i eth0 -f "tcp" -v

# Verify interface has traffic
sudo tcpdump -i eth0 -c 5

Permission Denied Error

# darkstat requires root
sudo darkstat -i eth0

# Or add user to network group
sudo usermod -a -G netdev username
sudo darkstat -i eth0

High CPU Usage

# Reduce history length
sudo darkstat -i eth0 -n 30

# Simplify filter
sudo darkstat -i eth0 -f "tcp port 80"

# Increase capture buffer size
sudo darkstat -i eth0 -s 32000

Hostnames Not Resolving

# Enable DNS resolution
sudo darkstat -i eth0

# Check DNS settings
cat /etc/resolv.conf

# Test resolution manually
nslookup 192.168.1.100

Service Won’t Start

# Check configuration file
cat /etc/darkstat/init.cfg

# Test manually
sudo darkstat -i eth0 -v

# View system logs
sudo journalctl -xe
sudo tail -f /var/log/darkstat.log

Performance Tuning

Optimize for High Traffic

# Increase buffer size
sudo darkstat -i eth0 -s 32000 -n 100

# Use larger history
sudo darkstat -i eth0 -n 100

# Disable DNS resolution if needed
sudo darkstat -i eth0 -l

Optimize for Low Resources

# Reduce history
sudo darkstat -i eth0 -n 10

# Smaller buffer
sudo darkstat -i eth0 -s 8192

# Filter traffic
sudo darkstat -i eth0 -f "tcp or udp"

Memory Management

# Check process memory
ps -p $(pgrep darkstat) -o rss=

# Monitor over time
watch -n 1 'ps -p $(pgrep darkstat) -o rss='

Security Considerations

Bind to Localhost Only

# Restrict dashboard access to local machine
sudo darkstat -i eth0 -b 127.0.0.1

Use Behind Reverse Proxy

# Use nginx to add authentication
# nginx listens on :80
# Forwards to darkstat on :666 with auth

Firewall Rules

# Allow only specific IPs
sudo ufw allow from 192.168.1.0/24 to any port 666

# Block external access
sudo ufw deny to any port 666 from any

HTTPS Access

# Use nginx/Apache SSL proxy
# Access via https://localhost/darkstat

Advanced Usage

Monitor Multiple Interfaces Simultaneously

# Create systemd service for each interface
sudo nano /etc/systemd/system/darkstat-eth0.service
sudo nano /etc/systemd/system/darkstat-wlan0.service

# Each on different port (666, 667)

Automated Backups

# Create cron job for daily backup
crontab -e
# 0 2 * * * tar czf /backup/darkstat-$(date +\%Y\%m\%d).tar.gz ~/.darkstat/

Data Analysis with sqlite3

# Query database directly
sqlite3 ~/.darkstat/darkstat.db

# Show tables
.tables

# Query host statistics
SELECT * FROM hosts LIMIT 10;

# Find top hosts by bytes
SELECT * FROM hosts ORDER BY bytes_sent+bytes_recv DESC LIMIT 10;

Additional Resources