Skip to content

Troubleshooting Guide

Jump to bottom
bmwl edited this page Nov 20, 2025 · 1 revision

Troubleshooting Guide

This page covers common issues and solutions for the Soft Data Diode Tools. For basic setup, see the main README.

Selenium Issues

Selenium crashes because it can't find a chrome/chromium driver

There are many reasons why the sender may crash with a Selenium error.

First, ensure you have both a browser and WebDriver installed and working on your OS. Selenium needs these components even on headless systems.

Second, be aware that some OS packages for Selenium are broken. Debian's python3-selenium package is known to have issues. The recommended approach is to use a virtual environment rather than OS packages.

For detailed Selenium setup instructions, refer to the Selenium Project documentation.

Performance Issues

Resource usage is too high

There are several strategies to reduce resource usage:

  1. Increase transmission interval: Use a larger value for --interval to send frames less frequently
  2. Reduce capture resolution: Lower the resolution of captured images
  3. Avoid resizing: Leave out the resolution parameter and the receiver will pass images through as-is
  4. Reduce JPEG quality: Lower the quality setting (default is 60, which balances quality vs size)
  5. Use eBPF packet forwarder: If using socat or similar, try the eBPF packet forwarder which uses less than 10% CPU
  6. Switch to PyPy: This is relatively hard to do and of limited value since the CPU-intensive libraries are already in high-performance C

Network Issues

Traffic isn't getting through to the receiver

Check for UDP packets using Wireshark or tcpdump:

tcpdump udp and port 5005

You should see a constant stream from sender to receiver on both hosts. Any firewalls in the path are highly likely to block this traffic, so ensure appropriate allow rules are in place.

File Sync Issues

Not all files are coming through during file sync

Dotfiles are skipped by default but can be enabled with a flag on the sender.

There is no guarantee that any given file will transfer successfully in any particular sync round, or that the receiver is even listening. The file sync uses best-effort delivery with a sliding window approach.

Solutions:

  • Increase --max-file-age to give files more opportunities to transfer
  • Shorten --sync-interval to attempt transfers more frequently
  • Schedule regular runs with --max-file-age 0 to catch straggler files that didn't make it in previous syncs

Very large files don't come through consistently

If transferring very large files, a single lost or corrupted packet will cause the receiver to discard the entire file.

Mitigations:

  • Increase the number of transfer attempts
  • Increase Network MTU (Jumbo Packets) and --max-packet-size
  • Be aware this is an inherently unreliable transfer method, and large files are the worst case

General Debugging

Things aren't working and I'm not sure what's happening

Start the sender or receiver with the --debug flag, or enable debugging in the config.json file. This produces verbose output that can help identify issues.

If debug output doesn't help, please create an issue in the repository.

Clone this wiki locally