net-bridge-tunnel

net-bridge-tunnel.py tunnels broadcast and multicast traffic bidirectionally between two Linux nodes over a single TCP connection.

Features

• server and client mode
• Length-prefixed TCP framing (4 bytes, network byte order)
• Scapy sniff + inject (sendp at Layer 2)
• Loop prevention with local MAC exclusion in the BPF filter
• Concurrent sniffing and receiving via threads
• Reconnect logic in client mode
• Graceful shutdown on SIGINT and SIGTERM

Requirements

• Linux
• Python 3.7+
• Root privileges (raw sockets)
• Scapy:

python3 -m pip install scapy

Usage

Server

sudo ./net-bridge-tunnel.py \
  --mode server \
  --port 9999 \
  --interface br0 \
  --filter "broadcast or multicast" \
  --loglevel INFO

Client

sudo ./net-bridge-tunnel.py \
  --mode client \
  --remote-ip 10.0.0.10 \
  --port 9999 \
  --interface br0 \
  --filter "broadcast or multicast" \
  --loglevel INFO

Important: Loop Prevention Filter

The script explicitly builds the sniff filter as:

({user_filter}) and not ether src {local_mac}

With default arguments this becomes:

(broadcast or multicast) and not ether src aa:bb:cc:dd:ee:ff

This prevents frames injected by the script from being captured again and re-tunneled.

Arguments

• --mode: server or client (required)
• --remote-ip: required in client mode
• --port: TCP port, default 9999
• --interface: local interface, e.g. eth0 or br0
• --filter: extra BPF filter, default broadcast or multicast
• --loglevel: DEBUG, INFO, WARNING

Systemd (Debian/Ubuntu)

Place files:

• net-bridge-tunnel.py to /usr/local/bin/net-bridge-tunnel.py
• net-bridge-tunnel-server.service to /etc/systemd/system/net-bridge-tunnel-server.service
• net-bridge-tunnel-client.service to /etc/systemd/system/net-bridge-tunnel-client.service

Make script executable:

sudo chmod +x /usr/local/bin/net-bridge-tunnel.py

Reload and enable service:

sudo systemctl daemon-reload
sudo systemctl enable --now net-bridge-tunnel-server.service
sudo systemctl status net-bridge-tunnel-server.service

For the client service: adjust --remote-ip and --interface in the unit file.

Follow logs:

sudo journalctl -u net-bridge-tunnel-server.service -f

Operational Notes

• The script requires root privileges because Scapy uses raw sockets.
• The client automatically retries on disconnect.
• The server accepts one connection, handles the session, then waits for a new connection.
• Frames larger than 10 MB are dropped as a safety measure.