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

Interface	Type	Example Use
eth0	Ethernet	Wired connection
wlan0	WiFi	Wireless connection
docker0	Virtual	Docker network
veth*	Virtual	Container interface
tun0	VPN	VPN 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

Section	Purpose
Bandwidth	Real-time and historical traffic
Top Hosts	Most active IP addresses
Protocols	Traffic breakdown by protocol
Ports	Connection ports and protocols
DNS	Resolved 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

Setting	Description
DNS cache	Stores resolved names
Reverse lookup	Convert IP to hostname
Local hosts	/etc/hosts file usage
Timeout	DNS 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"

Option	Default	Description
INTERFACE	eth0	Network interface to monitor
PORT	666	Web dashboard port
BINDADDR	localhost	IP address to bind to
QUERYINTERFACE	yes	Enable interface info queries
HISTORYLEN	50	History length in entries
BANNER	yes	Show 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

Feature	darkstat	ntopng
Size	Lightweight	Heavy
Setup	Simple	Complex
Web UI	Basic	Advanced
Resource Usage	Low	High
Geolocation	No	Yes
Alerts	Limited	Yes
Cost	Free	Free/Paid
Learning Curve	Easy	Medium

darkstat vs iftop

Feature	darkstat	iftop
Interface	Web	Terminal
Storage	Database	None
History	Yes	Real-time only
Bandwidth	Real-time	Real-time
Drill-down	Yes	Limited
Export	Yes	No
Protocols	TCP/UDP	Layer 3/4

darkstat vs vnstat

Feature	darkstat	vnstat
Protocol Detail	Yes	No
Real-time	Yes	Interval
Web UI	Yes	No
Database	SQLite	Custom
Portability	Good	Good
Install Size	Small	Small
Use Case	Real-time analysis	Long-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

• GitHub Repository: https://github.com/emikulic/darkstat
• Official Documentation: https://unix4lyfe.org/darkstat/
• tcpdump Filter Guide: https://www.tcpdump.org/papers/sniffing-faq.html
• NetFlow Tools: https://www.ntop.org/