Skip to content

armgit / core

Public Imported from GitHub
0

100% open-source IoT Platform - Integrate your devices, add intelligence, build custom apps

Add gateway tunneling throttling shell script (#2453)

Panos Kalogeropoulos0fe479fe57bd
diff --git a/test/src/test/groovy/org/openremote/test/gateway/throttling/README.md b/test/src/test/groovy/org/openremote/test/gateway/throttling/README.md
new file mode 100644
index 000000000..e6f4926e1
--- /dev/null
+++ b/test/src/test/groovy/org/openremote/test/gateway/throttling/README.md
@@ -0,0 +1,182 @@
+# Gateway Network Throttling Script
+
+A bash utility for simulating degraded network conditions between an OpenRemote gateway and a central instance. Useful
+for testing gateway resilience, reconnection logic, and behavior under poor network conditions.
+
+The reasoning for the creation of this script is to allow developers and testers to simulate real-world network issues
+such as latency, packet loss, and bandwidth limitations in a controlled manner. This applies for gateways that
+transfer large amounts of data to and from the central instance, but especially used for testing the gateway tunneling
+functionality, where large amounts of data is transferred (especially the frontend JS bundle), and even minor issues with
+connectivity can cause issues with interacting with the remote gateway.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ GATEWAY HOST │
+│ │
+│ ┌─────────────────────────────────────────────────────────────────────┐ │
+│ │ or-manager-1 container │ │
+│ │ │ │
+│ │ ┌─────────────┐ ┌──────────────────────────────────────┐ │ │
+│ │ │ Gateway │ │ eth0 interface │ │ │
+│ │ │ Manager │─────▶│ ┌─────────────────────────────────┐ │ │ │
+│ │ │ Process │ │ │ Traffic Control (tc) │ │ │ │
+│ │ └─────────────┘ │ │ ┌────────────────────────────┐ │ │ │ │
+│ │ │ │ │ netem qdisc (egress) │ │ │ │ │
+│ │ │ │ │ • delay: 75ms ± 25ms │ │ │ │ │
+│ │ │ │ │ • loss: 1% │ │ │ │ │
+│ │ │ │ │ • rate: 10mbit │ │ │ │ │
+│ │ │ │ └────────────────────────────┘ │ │ │ │
+│ │ │ └─────────────────────────────────┘ │ │ │
+│ │ │ ┌─────────────────────────────────┐ │ │ │
+│ │ │ │ iptables (ingress) │ │ │ │
+│ │ │ │ • 1% random packet drop │ │ │ │
+│ │ │ │ • or full DROP (blackhole) │ │ │ │
+│ │ │ └─────────────────────────────────┘ │ │ │
+│ │ └──────────────────────────────────────┘ │ │
+│ │ │ │ │
+│ │ (shared network namespace) │ │ │
+│ │ ▲ │ │ │
+│ │ │ │ │ │
+│ │ ┌────────┴────────┐ │ │ │
+│ │ │ pumba-nettools │ │ │ │
+│ │ │ (temporary) │ │ │ │
+│ │ │ Applies tc & │ │ │ │
+│ │ │ iptables rules │ │ │ │
+│ │ └─────────────────┘ │ │ │
+│ └─────────────────────────────────────────┼──────────────────────────┘ │
+│ │ │
+└────────────────────────────────────────────┼───────────────────────────────┘
+ │
+ ~~~~~~~~~~~~~~~│~~~~~~~~~~~~~~~
+ Internet │ (PUBLIC)
+ ~~~~~~~~~~~~~~~│~~~~~~~~~~~~~~~
+ │
+ ▼
+ ┌──────────────────────────────┐
+ │ CENTRAL INSTANCE │
+ │ (e.g., demo.openremote.app)│
+ │ │
+ │ ┌──────────────────────┐ │
+ │ │ Central Manager │ │
+ │ └──────────────────────┘ │
+ └──────────────────────────────┘
+```
+
+### Throttle Mode (`on`)
+
+```
+Gateway Central
+ │ │
+ │ ──────── outbound packet ────────▶ │
+ │ [+75ms delay, ±25ms jitter, 1% loss, 10mbit] │
+ │ │
+ │ ◀──────── inbound packet ───────── │
+ │ [1% random drop] │
+ │ │
+```
+
+### Drop Mode (`drop`)
+
+```
+Gateway Central
+ │ │
+ │ ────── outbound packet ──────▶ ╳ BLOCKED │
+ │ │
+ │ ╳ BLOCKED ◀────── inbound packet ──── │
+ │ │
+ │ (complete blackhole for N seconds) │
+```
+
+## Prerequisites
+
+- Docker installed and running
+- The `or-manager-1` container must be running
+- The script uses [pumba-alpine-nettools](https://github.com/alexei-led/pumba) for network manipulation
+
+## Configuration
+
+Edit these variables at the top of `throttle.sh`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTAINER` | `or-manager-1` | Target Docker container |
+| `TARGET_IP` | (empty) | Public IP of the central instance (e.g., resolved IP of `demo.openremote.app`) |
+| `DELAY` | `75ms` | Network latency added to packets |
+| `JITTER` | `25ms` | Variation in latency |
+| `LOSS` | `1%` | Percentage of packets to drop |
+| `RATE` | `10mbit` | Bandwidth limit |
+
+**Important:** You must set `TARGET_IP` before using the script. Use `dig` to resolve the hostname:
+```bash
+TARGET_IP=$(dig +short demo.openremote.app | head -1)
+```
+
+## Usage
+
+```bash
+./throttle.sh [command]
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `on` | Enable throttling with configured delay, jitter, loss, and rate limit |
+| `off` | Disable all throttling and restore normal connectivity |
+| `toggle` | Toggle throttling on/off (default if no command given) |
+| `drop [seconds]` | Completely block connectivity for specified duration (default: 5s) |
+| `status` | Show current throttling status |
+
+### Examples
+
+```bash
+# Enable throttling
+./throttle.sh on
+
+# Check status
+./throttle.sh status
+
+# Simulate connection loss for 10 seconds
+./throttle.sh drop 10
+
+# Disable throttling
+./throttle.sh off
+
+# Toggle (on if off, off if on)
+./throttle.sh
+```
+
+## How It Works
+
+The script manipulates network traffic using two mechanisms:
+
+### Egress Throttling (tc/netem)
+Uses Linux Traffic Control (`tc`) with the `netem` qdisc to:
+- Add configurable latency and jitter
+- Simulate packet loss
+- Limit bandwidth
+
+Traffic shaping is applied only to packets destined for `TARGET_IP`.
+
+### Connection Dropping (iptables)
+Uses `iptables` rules to:
+- Drop incoming packets from `TARGET_IP` (for throttle mode: 1% random drop)
+- Completely block bidirectional traffic (for drop mode)
+
+### Docker Integration
+The script runs a temporary container (`pumba-alpine-nettools`) that shares the network namespace with `or-manager-1` (`--net=container:$CONTAINER`). This allows modifying the network stack of the manager container without installing tools inside it.
+
+## Troubleshooting
+
+**"Permission denied" errors:**
+Ensure the script is executable: `chmod +x throttle.sh`
+
+**No effect observed:**
+- Verify `TARGET_IP` is set correctly
+- Check that `or-manager-1` container is running
+- Run `./throttle.sh status` to verify rules are applied
+
+**Cannot pull Docker image:**
+The script requires access to `ghcr.io`. Ensure network/firewall allows this.
diff --git a/test/src/test/groovy/org/openremote/test/gateway/throttling/throttle.sh b/test/src/test/groovy/org/openremote/test/gateway/throttling/throttle.sh
new file mode 100644
index 000000000..2ab4be2e2
--- /dev/null
+++ b/test/src/test/groovy/org/openremote/test/gateway/throttling/throttle.sh
@@ -0,0 +1,98 @@
+#!/bin/bash
+CONTAINER="or-manager-1"
+TC_IMAGE="ghcr.io/alexei-led/pumba-alpine-nettools:latest"
+TARGET_IP="" # Set the public IP of the central instance here, e.g., demo.openremote.app . I use dig for this.
+DELAY="75ms"
+JITTER="25ms"
+LOSS="1%"
+RATE="10mbit"
+
+run_tc() {
+ docker run --rm --net=container:$CONTAINER --cap-add NET_ADMIN --entrypoint /bin/sh $TC_IMAGE -c "$1"
+}
+
+is_active() {
+ run_tc "tc qdisc show dev eth0" 2>/dev/null | grep -q "prio"
+}
+
+is_dropped() {
+ run_tc "iptables -L INPUT -n" 2>/dev/null | grep -q "$TARGET_IP.*DROP"
+}
+
+start_throttle() {
+ run_tc "
+ # Egress throttling (delay + loss + rate)
+ tc qdisc add dev eth0 root handle 1: prio
+ tc qdisc add dev eth0 parent 1:3 handle 30: netem delay $DELAY $JITTER loss $LOSS rate $RATE
+ tc filter add dev eth0 protocol ip parent 1:0 prio 3 u32 match ip dst $TARGET_IP/32 flowid 1:3
+ # Ingress packet loss (iptables)
+ iptables -A INPUT -s $TARGET_IP -m statistic --mode random --probability 0.01 -j DROP
+ "
+}
+
+stop_throttle() {
+ run_tc "
+ tc qdisc del dev eth0 root
+ while iptables -D INPUT -s $TARGET_IP -m statistic --mode random --probability 0.01 -j DROP 2>/dev/null; do :; done
+ " 2>/dev/null
+}
+
+start_drop() {
+ run_tc "
+ iptables -A INPUT -s $TARGET_IP -j DROP
+ iptables -A OUTPUT -d $TARGET_IP -j DROP
+ "
+}
+
+stop_drop() {
+ run_tc "
+ while iptables -D INPUT -s $TARGET_IP -j DROP 2>/dev/null; do :; done
+ while iptables -D OUTPUT -d $TARGET_IP -j DROP 2>/dev/null; do :; done
+ "
+}
+
+case "${1:-toggle}" in
+ on)
+ stop_throttle
+ stop_drop
+ start_throttle
+ echo "Throttling ON for $TARGET_IP"
+ ;;
+ off)
+ stop_throttle
+ stop_drop
+ echo "Throttling OFF"
+ ;;
+ toggle)
+ if is_active; then
+ stop_throttle
+ echo "Throttling OFF"
+ else
+ start_throttle
+ echo "Throttling ON for $TARGET_IP"
+ fi
+ ;;
+ drop)
+ DURATION="${2:-5}"
+ start_drop
+ echo "Connection DROPPED for ${DURATION}s..."
+ sleep "$DURATION"
+ stop_drop
+ echo "Connection RESTORED"
+ ;;
+ status)
+ echo "=== Status for $TARGET_IP ==="
+ if is_dropped; then
+ echo "Connection: DROPPED (blackhole)"
+ elif is_active; then
+ echo "Connection: THROTTLED"
+ run_tc "tc qdisc show dev eth0"
+ else
+ echo "Connection: NORMAL (no throttling)"
+ fi
+ ;;
+ *)
+ echo "Usage: $0 [on|off|toggle|drop [seconds]|status]"
+ exit 1
+ ;;
+esac