Daemon Troubleshooting

Common issues and solutions for Scanopy daemons.

Daemon Issues

Daemon Not Connecting to Server

Symptoms: Daemon shows as offline in the UI, or logs show connection errors

Diagnosis:

# Check daemon logs
docker logs scanopy-daemon

# Test connectivity to server
curl https://your-server-url/api/health

Solutions:

1. Verify server URL: Ensure SCANOPY_SERVER_URL is correct and reachable from the daemon host
2. Check API key: Verify the API key is valid and not expired in Manage > API Keys
3. Firewall rules: Ensure outbound HTTPS (port 443) is allowed from the daemon host

Discovery Fails with "CONCURRENT_SCANS too high"

Symptoms: Daemon crashes or runs out of memory during scans

Solution: Reduce concurrent scans in daemon configuration:

Docker:

environment:
  - SCANOPY_CONCURRENT_SCANS=10 # Reduce from default

Binary:

scanopy-daemon --concurrent-scans 10 ...

See Daemon Configuration for recommended values.

"Too Many Open Files" Error

Symptoms: Critical error scanning: Too many open files (os error 24) in daemon logs

Causes: System file descriptor limit is too low for the configured concurrent scans.

Solutions:

1. Reduce concurrent scans (easiest):

   environment:
     - SCANOPY_CONCURRENT_SCANS=10

2. Increase system file descriptor limit:

   # Check current limit
   ulimit -n
   
   # Increase temporarily
   ulimit -n 65535
   
   # Increase permanently (add to /etc/security/limits.conf)
   * soft nofile 65535
   * hard nofile 65535

3. For Docker: Add to your daemon container:

   ulimits:
     nofile:
       soft: 65535
       hard: 65535

Permission Denied Errors (Linux)

Symptoms: "Permission denied" when accessing Docker socket

Solution: Add user to docker group:

sudo usermod -aG docker $USER
newgrp docker

Log out and back in for changes to take effect.

If you're using a Docker socket proxy and getting permission errors, see Docker Socket Proxy troubleshooting.

Daemon Stops When Terminal Closes

Symptoms: Daemon runs in foreground and stops when SSH session ends

Solution: Install as a systemd service (see Installing a Daemon), or run with a process manager like screen or tmux.

Discovery Issues

Hosts Not Discovered / Missing IPs

Symptoms: Discovery completes but some known hosts are missing from results. Manual arping to the missing IPs works fine.

Most likely cause: Switch rate limiting is dropping ARP packets before they reach hosts or before responses return.

Understanding ARP Scanning

Scanopy uses broadcast ARP for fast host discovery. For each target IP, we send an ARP "who-has" request and wait for a reply. This is faster and more reliable than TCP/UDP probing because hosts cannot firewall ARP and still communicate on the network.

However, many managed switches implement Dynamic ARP Inspection (DAI) to prevent ARP spoofing attacks. DAI rate-limits ARP packets on untrusted ports to a maximum number of packets per second (pps). When the limit is exceeded, the switch either drops excess packets silently or disables the port entirely.

Known default rate limits:

If your switch has DAI enabled and Scanopy sends ARP faster than the limit allows, excess packets are dropped and those hosts appear offline.

How Retries Work

Scanopy uses targeted retries rather than simple broadcast flooding:

1. Round 1: Send ARP request to all target IPs at the configured rate
2. Wait: Collect responses for 3 seconds
3. Round 2: Send ARP requests only to IPs that didn't respond
4. Repeat: Continue for the configured number of retry rounds
5. Final wait: Extra collection period for late-arriving responses

This approach minimizes total packets sent (only non-responders are retried) while giving slow or rate-limited hosts multiple chances to be discovered.

Example with arp_retries=2 (default) scanning a /24:

If rate limiting caused packet loss in round 1, rounds 2 and 3 retry only those hosts—often successfully since the burst is smaller.

Diagnosis

1. Check if your switch has DAI enabled. Consult your switch documentation for how to view DAI configuration and statistics. Look for rate limit violations or dropped ARP packets.

2. Check for port shutdown. Some switches (notably Cisco) disable the port entirely when the rate limit is exceeded. If your scanner lost network connectivity during a scan, this is likely the cause.

3. Test with manual arping:

   # If this finds the host but Scanopy doesn't, rate limiting is likely
   arping -c 3 <missing-ip>

Solutions

Option 1: Reduce ARP scan rate

Lower arp_rate_pps to stay within your switch's DAI limit:

# CLI
scanopy-daemon --arp-rate-pps 15

# Environment variable
export SCANOPY_ARP_RATE_PPS=15

# Docker
environment:
  - SCANOPY_ARP_RATE_PPS=15

Recommended values:

Option 2: Increase retries

If rate limiting causes occasional packet loss, more retries give hosts additional chances to respond:

# CLI
scanopy-daemon --arp-retries 4   # 5 total rounds (default is 2 = 3 rounds)

# Environment variable
export SCANOPY_ARP_RETRIES=4

Higher retries help when:

• Rate limiting drops some packets but not all
• Hosts are slow to respond (busy or sleeping devices)
• Network has high background traffic

The tradeoff is longer scan time, but since retries only target non-responders, the overhead is usually small.

Option 3: Adjust your switch DAI configuration

If you control the switch, you can increase the rate limit on the scanner's port or mark it as trusted (no rate limit). Consult your switch documentation for the specific commands.

Option 4: Use Npcap for broadcast ARP (Windows only)

On Windows, Scanopy defaults to the SendARP API which scans hosts sequentially. For faster scanning, you can enable Npcap broadcast ARP:

# CLI
scanopy-daemon --use-npcap-arp

# Environment variable
export SCANOPY_USE_NPCAP_ARP=true

# Docker
environment:
  - SCANOPY_USE_NPCAP_ARP=true

Requirements:

• Npcap must be installed (free for personal use)
• During Npcap installation, enable "WinPcap API-compatible Mode"

When to use Npcap:

• Scanning large subnets where sequential SendARP is too slow
• You need the same broadcast ARP behavior as Linux/macOS

When to stick with SendARP (default):

• Npcap is not installed or cannot be installed
• Scanning small networks where speed doesn't matter
• You want zero additional dependencies

Tuning for Your Network

See Daemon Configuration for all ARP settings.

Discovery Takes Hours

Symptoms: Network discovery takes 10+ hours to complete

Most likely cause: You're scanning a Docker bridge network. The default 172.17.0.0/16 is 65,536 IPs.

Solutions:

1. Remove large subnets: In your Network Scan discovery, remove any Docker bridge networks (172.17.0.0/16, etc.)

2. Use Docker discovery instead: It queries the Docker API directly and takes seconds

3. Check your subnet list: Only scan subnets that actually contain hosts

Topology Empty After Discovery

Symptoms: Discovery completes but topology shows nothing

Check these:

1. Discovery errors: Check Discover > Sessions for failures
2. Network filter: Check topology options panel — wrong network may be selected
3. Refresh mode: Press "Rebuild" or change from manual to auto to get live updates
4. Service filters: Category filters may be hiding everything
5. Reachability: Verify daemon can actually reach the target network

Getting Help

If your issue isn't covered here:

• Discord: Join our Discord community
• GitHub Issues: Open an issue