100% open-source IoT Platform - Integrate your devices, add intelligence, build custom apps
Java asset-managementbuildingdashboarddataplatformdevice-managementedge-computingenergyenergy-managementenergy-monitorfleet-managementfleet-telematicsiotiot-applicationiot-platformmodbusmqttmqtt-brokerota-updaterules-enginesmartcity
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.mdnew file mode 100644index 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.shnew file mode 100644index 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