Upgrade from 1.4.x to 1.5.x breaks all app connectivity (tested on Raspberry Pi 5)

[jleaders]

Missing iptables FORWARD rules on umbrel_main_network means no apps can get a port.

Environment

• Device: Raspberry Pi 5
• OS: UmbrelOS 1.5
• Upgrade Path: Upgraded from previous version (issue appeared after upgrade)
• Docker Version: (as shipped with UmbrelOS 1.5)

Problem Description

After upgrading to UmbrelOS 1.5 on Raspberry Pi 5, all Umbrel apps become inaccessible from the local network. Containers are
running and healthy, but connections to any app port (e.g., n8n on 5678, komodo on 9120) fail or are rejected.

Symptoms

• ✅ Docker containers start successfully (docker ps shows all containers running)
• ✅ SSH to Umbrel works fine
• ❌ All app URLs timeout or connection refused from external devices
• ❌ curl from LAN to umbrel.local:<port> fails
• ❌ curl from umbrel host to localhost:<port> gets "Connection reset by peer"
• ❌ Inter-container communication fails (app_proxy cannot reach backend containers)

Root Cause

The umbrel_main_network Docker bridge (e.g., br-bfea11e6272f) is missing its iptables FORWARD chain rules after the
upgrade.

Expected rules (present on other bridges):

iptables -A FORWARD -o br-xxx -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
iptables -A FORWARD -i br-xxx ! -o br-xxx -j ACCEPT
iptables -A FORWARD -i br-xxx -o br-xxx -j ACCEPT

Actual state: No FORWARD rules exist for the umbrel_main_network bridge, so all traffic hits the default DROP policy.

Evidence

Other Docker networks have proper rules:

$ sudo iptables -L FORWARD -n -v | grep br-eb4acdafcd65
    3   255 ACCEPT     all  --  *      br-eb4acdafcd65  0.0.0.0/0    0.0.0.0/0    ctstate RELATED,ESTABLISHED
    0     0 DOCKER     all  --  *      br-eb4acdafcd65  0.0.0.0/0    0.0.0.0/0
    3   207 ACCEPT     all  --  br-eb4acdafcd65 !br-eb4acdafcd65  0.0.0.0/0    0.0.0.0/0
    0     0 ACCEPT     all  --  br-eb4acdafcd65 br-eb4acdafcd65  0.0.0.0/0    0.0.0.0/0

umbrel_main_network bridge has NO rules:

$ sudo iptables -L FORWARD -n -v | grep br-bfea11e6272f
(no output)

Workaround

Manually add the missing iptables rules after each reboot:

# Find the umbrel_main_network bridge
NETWORK_ID=$(docker network inspect umbrel_main_network --format '{{.Id}}' | cut -c1-12)
BRIDGE="br-${NETWORK_ID}"

# Add FORWARD rules
iptables -I FORWARD -o $BRIDGE -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
iptables -I FORWARD -i $BRIDGE ! -o $BRIDGE -j ACCEPT
iptables -I FORWARD -i $BRIDGE -o $BRIDGE -j ACCEPT
iptables -I FORWARD -o $BRIDGE -j ACCEPT

A persistent startup script is needed since the bridge network ID changes on each reboot.

Impact

- Severity: Critical - all apps are completely inaccessible
- Affected Users: Raspberry Pi 5 users who upgraded to UmbrelOS 1.5
- Workaround Complexity: High - requires manual iptables configuration and startup script

Additional Context

This may be related to the known Raspberry Pi OS deprecation of iptables in favor of nftables, which causes Docker networking
 issues. However, other Docker bridges on the same system have proper rules, suggesting this is specific to how UmbrelOS 1.5
creates or manages the umbrel_main_network.

The network ID changes on each reboot (e.g., br-bfea11e6272f → br-8e41e5107c9d → br-07efc0bf5a6e), which may indicate the
network is being recreated rather than persisted, potentially contributing to the missing iptables rules.

[jleaders]

Workaround: Automated Startup Script

This script automatically fixes the missing iptables rules on every boot.

Installation

Run these commands on your Umbrel system:

# 1. Create the fix script
sudo tee /usr/local/bin/fix-umbrel-network.sh > /dev/null << 'EOF'
#!/bin/bash
# Fix for UmbrelOS 1.5 iptables issue on Raspberry Pi 5
# Adds missing FORWARD rules for umbrel_main_network bridge

set -e

echo "[$(date)] Starting Umbrel network fix..."

# Wait for Docker to be ready
max_wait=60
waited=0
while [ $waited -lt $max_wait ]; do
    if docker info &>/dev/null; then
        echo "[$(date)] Docker is ready"
        break
    fi
    echo "[$(date)] Waiting for Docker..."
    sleep 2
    waited=$((waited + 2))
done

if [ $waited -ge $max_wait ]; then
    echo "[$(date)] ERROR: Docker not ready after ${max_wait}s"
    exit 1
fi

# Find the umbrel_main_network bridge name dynamically
NETWORK_ID=$(docker network inspect umbrel_main_network --format '{{.Id}}' 2>/dev/null | cut -c1-12)

if [ -z "$NETWORK_ID" ]; then
    echo "[$(date)] ERROR: Could not find umbrel_main_network"
    exit 1
fi

BRIDGE="br-${NETWORK_ID}"

# Verify bridge exists
if ! ip link show $BRIDGE &>/dev/null; then
    echo "[$(date)] ERROR: Bridge $BRIDGE does not exist"
    exit 1
fi

echo "[$(date)] Found umbrel_main_network bridge: $BRIDGE"

# Add FORWARD rules for umbrel_main_network
echo "[$(date)] Adding FORWARD chain rules for $BRIDGE..."

# Rule 1: Allow established connections to bridge
if ! iptables -C FORWARD -o $BRIDGE -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT 2>/dev/null; then
    iptables -I FORWARD -o $BRIDGE -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
    echo "[$(date)] Added: FORWARD -o $BRIDGE (RELATED,ESTABLISHED)"
else
    echo "[$(date)] Rule already exists: FORWARD -o $BRIDGE (RELATED,ESTABLISHED)"
fi

# Rule 2: Allow outgoing from bridge
if ! iptables -C FORWARD -i $BRIDGE ! -o $BRIDGE -j ACCEPT 2>/dev/null; then
    iptables -I FORWARD -i $BRIDGE ! -o $BRIDGE -j ACCEPT
    echo "[$(date)] Added: FORWARD -i $BRIDGE ! -o $BRIDGE"
else
    echo "[$(date)] Rule already exists: FORWARD -i $BRIDGE ! -o $BRIDGE"
fi

# Rule 3: Allow inter-container traffic on bridge
if ! iptables -C FORWARD -i $BRIDGE -o $BRIDGE -j ACCEPT 2>/dev/null; then
    iptables -I FORWARD -i $BRIDGE -o $BRIDGE -j ACCEPT
    echo "[$(date)] Added: FORWARD -i $BRIDGE -o $BRIDGE"
else
    echo "[$(date)] Rule already exists: FORWARD -i $BRIDGE -o $BRIDGE"
fi

# Rule 4: Allow all incoming to bridge
if ! iptables -C FORWARD -o $BRIDGE -j ACCEPT 2>/dev/null; then
    iptables -I FORWARD -o $BRIDGE -j ACCEPT
    echo "[$(date)] Added: FORWARD -o $BRIDGE"
else
    echo "[$(date)] Rule already exists: FORWARD -o $BRIDGE"
fi

echo "[$(date)] Umbrel network fix completed successfully!"
EOF

# 2. Make the script executable
sudo chmod +x /usr/local/bin/fix-umbrel-network.sh

# 3. Create systemd service
sudo tee /etc/systemd/system/fix-umbrel-network.service > /dev/null << 'EOF'
[Unit]
Description=Fix Umbrel Network iptables (UmbrelOS 1.5 workaround)
After=docker.service
Requires=docker.service
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/fix-umbrel-network.sh
RemainAfterExit=yes
StandardOutput=journal
StandardError=journal
Restart=on-failure
RestartSec=10
StartLimitBurst=3

[Install]
WantedBy=multi-user.target
EOF

# 4. Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable fix-umbrel-network.service
sudo systemctl start fix-umbrel-network.service

# 5. Verify it worked
echo ""
echo "=== Installation Complete ==="
echo ""
sudo systemctl status fix-umbrel-network.service --no-pager

Verification

After installation, verify the fix is working:

# Check if service is enabled
systemctl is-enabled fix-umbrel-network.service

# View service logs
sudo journalctl -u fix-umbrel-network.service -n 50

# Test app connectivity (replace PORT with your app's port)
curl -I http://umbrel.local:PORT

Test After Reboot

sudo reboot
# Wait 2-3 minutes for system to fully boot, then:
curl -I http://umbrel.local:PORT

The service will automatically:
- Wait for Docker to be ready
- Find the umbrel_main_network bridge (handles changing network IDs)
- Add the missing iptables FORWARD rules
- Retry up to 3 times if Docker/Umbrel isn't ready yet

Uninstall

If you want to remove the workaround later:

sudo systemctl stop fix-umbrel-network.service
sudo systemctl disable fix-umbrel-network.service
sudo rm /etc/systemd/system/fix-umbrel-network.service
sudo rm /usr/local/bin/fix-umbrel-network.sh
sudo systemctl daemon-reload