URnetwork helper

All support provider binary deployment.

Advanced: Providers Through Shadowsocks Proxy

Run URnetwork providers through a Shadowsocks proxy for enhanced privacy or specific egress routing.

Shadowsocks vs SOCKS5:

Architecture:

┌─────────────────────────────────────────┐
│        URnetwork Provider Container     │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ Provider     │──│ ss-local     │────┼───▶ Shadowsocks Server
│  │ (egress)     │  │ (SOCKS5:1080)│    │    (encrypted tunnel)
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘

Shadowsocks Config Format:

Shadowsocks/proxy/server/port/method/country/password
Example:
Shadowsocks/proxy/138.249.106.2/64619/aes-256-gcm/France/NedyYDqp

Dockerfile Setup:

FROM bringyour/community-provider:g4-latest
Install shadowsocks-libev
RUN apt-get update && apt-get install -y \
    shadowsocks-libev \
    && rm -rf /var/lib/apt/lists/*
Copy config
COPY shadowsocks.json /etc/shadowsocks-libev/config.json
Copy startup script
COPY start-shadowsocks.sh /start-shadowsocks.sh
RUN chmod +x /start-shadowsocks.sh
EXPOSE 1080
ENTRYPOINT ["/start-shadowsocks.sh"]

shadowsocks.json:

{
    "server": "YOURIP",
    "server_port": YOURPORT,
    "local_port": YOURPORT,
    "local_address": "YOURIP",
    "password": "YOURpass",
    "timeout": 300,
    "method": "YOURMETHOD"
}

start-shadowsocks.sh:

#!/bin/bash
set -e
Start shadowsocks client
ss-local -c /etc/shadowsocks-libev/config.json &
SS_PID=$!
echo "Shadowsocks client started (PID: $SS_PID)"
Wait for shadowsocks to be ready
sleep 3
Verify shadowsocks is listening
if ! netstat -tlnp 2>/dev/null | grep -q ':1080' && \
   ! ss -tlnp 2>/dev/null | grep -q ':1080'; then
    if ! pgrep -x "ss-local" > /dev/null; then
        echo "ERROR: Shadowsocks not running"
        exit 1
    fi
fi
echo "Shadowsocks proxy ready on 127.0.0.1:1080"
Start URnetwork provider with proxy environment
export HTTP_PROXY="socks5://127.0.0.1:1080"
export HTTPS_PROXY="socks5://127.0.0.1:1080"
export ALL_PROXY="socks5://127.0.0.1:1080"
exec /usr/local/sbin/bringyour-provider provide

Build Image:

docker build -t urnetwork-shadowsocks:latest .

Run Shadowsocks Provider:

# Create JWT directory
mkdir -p ~/.urnetwork-ss-1
echo "" > ~/.urnetwork-ss-1/jwt
Run container
docker run -d \
  --name urnetwork-shadowsocks-1 \
  --restart always \
  -v ~/.urnetwork-ss-1:/root/.urnetwork \
  -e WARP_ENV=community \
  urnetwork-shadowsocks:latest

Scale to Multiple Providers:

JWT=""
for i in $(seq 1 10); do
  mkdir -p ~/.urnetwork-ss-$i
  echo "$JWT" > ~/.urnetwork-ss-$i/jwt
  
  docker run -d \
    --name urnetwork-shadowsocks-$i \
    --restart always \
    -v ~/.urnetwork-ss-$i:/root/.urnetwork \
    -e WARP_ENV=community \
    urnetwork-shadowsocks:latest
done

Verification:

# Check container status
docker ps --filter "name=urnetwork-shadowsocks"
Check shadowsocks logs
docker logs urnetwork-shadowsocks-1 | grep "listening"
Should show: "listening at 0.0.0.0:1080"
Check provider logs
docker logs urnetwork-shadowsocks-1 | grep "Provider"
Should show: "Provider XXX started"

Common Shadowsocks Methods: | Method | Description | |--------|-------------| | aes-256-gcm | Recommended, hardware-accelerated | | aes-128-gcm | Faster, slightly less secure | | chacha20-ietf-poly1305 | Good for mobile/ARM devices |

Troubleshooting:

Quick Reference: Proxied Provider

Build Image:

docker build -t urnetwork-proxied:latest .

Run Proxied Provider:

docker run --name urnetwork-proxied \
  --cap-add=NET_ADMIN \
  --mount type=bind,source=$HOME/.urnetwork,target=/root/.urnetwork \
  --restart always \
  -d urnetwork-proxied:latest

Verify Egress IP:

docker exec urnetwork-proxied curl -s http://ipinfo.io/ip

Files Needed:

Proxy Format:

socks5/45.91.198.75:7778/username/password

Quick Reference: Shadowsocks Provider

Build Image:

docker build -t urnetwork-shadowsocks:latest .

Run Shadowsocks Provider:

docker run -d \
  --name urnetwork-shadowsocks-1 \
  --restart always \
  -v ~/.urnetwork-ss-1:/root/.urnetwork \
  -e WARP_ENV=community \
  urnetwork-shadowsocks:latest

Shadowsocks Config Format:

Shadowsocks/proxy/server/port/method/country/password
Example:
Shadowsocks/proxy/138.249.106.2/64619/aes-256-gcm/France/NedyYDqp

Files Needed:

Provider Monitoring

Quick Status Check

# All URnetwork containers
docker ps --format "table {{.Names}}\t{{.Status}}" | grep urnetwork
Count by type
docker ps --format "{{.Names}}" | grep -c "urnetwork-provider"
docker ps --format "{{.Names}}" | grep -c "urnetwork-proxied"
docker ps --format "{{.Names}}" | grep -c "urnetwork-shadowsocks"

Verify Actually Providing vs Restarting

Check for authentication errors:

# Count "Unauthorized" errors in logs
docker logs urnetwork-provider-1 2>&1 | grep -c "Unauthorized"
Check recent restarts
docker ps --format "table {{.Names}}\t{{.Status}}" | grep urnetwork-provider
"Up X minutes" = healthy, "Restarting" = auth/connection issues

Check provider logs for success:

# Good: "Provider XXX started" without errors
docker logs urnetwork-proxied-1 2>&1 | grep "Provider.*started"
Bad: Stack traces with "401 Unauthorized"
docker logs urnetwork-provider-1 2>&1 | tail -20

Provider Health Summary Script

#!/bin/bash
echo "=== URnetwork Provider Health ==="
for container in $(docker ps -a --format "{{.Names}}" | grep urnetwork | sort); do
  status=$(docker ps --filter "name=$container" --format "{{.Status}}")
  errors=$(docker logs $container 2>&1 | grep -c "Unauthorized" || echo "0")
  if echo "$status" | grep -q "Restarting"; then
    echo "❌ $container: $status (Errors: $errors)"
  else
    echo "✅ $container: $status"
  fi
done

Multi-VPS Deployment

Architecture Pattern

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   VPS 1 (Host)  │  │   VPS 2 (DE)    │  │   VPS 3 (US)    │
│  ┌───────────┐  │  │  ┌───────────┐  │  │  ┌───────────┐  │
│  │ Providers │  │  │  │ Providers │  │  │  │ Providers │  │
│  │ (10 reg)  │  │  │  │ (10 reg)  │  │  │  │ (10 reg)  │  │
│  └───────────┘  │  │  └───────────┘  │  │  └───────────┘  │
│  ┌───────────┐  │  │                 │  │                 │
│  │ Proxied   │  │  │                 │  │                 │
│  │ (10 sock) │  │  │                 │  │                 │
│  └───────────┘  │  │                 │  │                 │
└─────────────────┘  └─────────────────┘  └─────────────────┘
         │                    │                    │
         └────────────────────┴────────────────────┘
                              │
                    Single JWT on each VPS
                    /root/.urnetwork/jwt

Deployment Steps

1. Prepare JWT on Host VPS:

# Host VPS (source of truth)
mkdir -p /root/.urnetwork
echo "" > /root/.urnetwork/jwt

2. Deploy to Remote VPS:

VPS_IP="YOURIP"
VPS_USER="YOURuser"
VPS_PASS="YOURpassword"
Copy JWT to remote
sshpass -p "$VPS_PASS" scp /root/.urnetwork/jwt $VPS_USER@$VPS_IP:/home/$VPS_USER/.urnetwork/jwt
SSH and create /root/.urnetwork (if needed)
sshpass -p "$VPS_PASS" ssh $VPS_USER@$VPS_IP 'sudo mkdir -p /root/.urnetwork && sudo cp /home/'$VPS_USER'/.urnetwork/jwt /root/.urnetwork/jwt'
Launch providers on remote
sshpass -p "$VPS_PASS" ssh $VPS_USER@$VPS_IP '
  for i in $(seq 1 10); do
    docker run -d --name urnetwork-provider-vps-$i \
      -v /root/.urnetwork:/root/.urnetwork \
      --restart always \
      bringyour/community-provider:g4-latest provide
  done
'

3. Scale Pattern:

# Launch N providers on current host
launch_providers() {
  local count=$1
  local prefix=$2
  for i in $(seq 1 $count); do
    docker run -d --name ${prefix}-$i \
      -v /root/.urnetwork:/root/.urnetwork \
      --restart always \
      bringyour/community-provider:g4-latest provide
  done
}
Usage
launch_providers 10 "urnetwork-provider"
launch_providers 10 "urnetwork-proxied"

Troubleshooting Guide

401 Unauthorized Errors

Symptoms:

Causes & Fixes:

| Cause | Fix | |-------|-----| | JWT expired | Get fresh auth code from https://ur.io | | JWT malformed | Re-copy JWT, ensure no extra whitespace | | Wrong JWT location | Verify mounted at /root/.urnetwork/jwt | | JWT permissions | Ensure readable: chmod 644 /root/.urnetwork/jwt |

Quick Fix:

# 1. Get new auth code from https://ur.io
2. Exchange for JWT
curl -X POST https://api.bringyour.com/auth/code-login \
  -d '{"auth_code": "YOUR_CODE"}' | jq -r ".by_jwt" > /root/.urnetwork/jwt
3. Restart all providers
docker restart $(docker ps -q --filter "name=urnetwork")

Restart Loops

Check restart count:

docker ps --format "table {{.Names}}\t{{.Status}}" | grep urnetwork

Common causes:

| Pattern | Likely Cause | Solution | |---------|--------------|----------| | Restarting every 5-10s | 401 Unauthorized | Refresh JWT | | Restarting every 30s | Proxy connection issue | Check SOCKS5/Shadowsocks server | | Up for hours then restart | Network instability | Check --restart always is set |

Debug restart loop:

# Watch real-time logs
docker logs -f urnetwork-provider-1
Check exit code
docker inspect urnetwork-provider-1 --format='{{.State.ExitCode}}'

Proxy Connection Issues (Proxied Providers)

Symptoms:

Diagnose:

# Test SOCKS5 proxy manually
curl -x socks5://username:password@proxy_ip:port http://ipinfo.io/ip
Check shadowsocks is listening
docker exec urnetwork-shadowsocks-1 ss -tlnp | grep 1080
Verify iptables rules (for proxied containers)
docker exec urnetwork-proxied-1 iptables -t nat -L REDSOCKS

Fix proxy config:

# Update shadowsocks.json and rebuild
docker build -t urnetwork-shadowsocks:latest .
docker restart urnetwork-shadowsocks-{1..10}

Container Won't Start

Check:

# Port conflicts
docker logs urnetwork-provider-1 2>&1 | grep "bind"
Mount issues
docker logs urnetwork-provider-1 2>&1 | grep "mount"
Disk space
df -h
Docker daemon
docker system info

Mass Operations

Restart all providers:

docker restart $(docker ps -q --filter "name=urnetwork")

Stop all providers:

docker stop $(docker ps -q --filter "name=urnetwork")

Remove all providers (destructive):

docker rm -f $(docker ps -aq --filter "name=urnetwork")

View all logs:

for c in $(docker ps --format "{{.Names}}" | grep urnetwork); do
  echo "=== $c ==="
  docker logs $c 2>&1 | tail -5
done

Full docs: https://docs.ur.io