Tunnel Troubleshooting Guide
This guide helps diagnose and resolve common issues with Peridio tunnels.
Common Issues
Tunnel Stuck in "Created" State
Symptoms:
- Tunnel remains in "created" state after several minutes
- Never transitions to "open" state
Possible Causes:
- Device is offline
- Peridiod agent not running
- Network connectivity issues
- Firewall blocking outbound connections
Solutions:
Check device status:
peridio devices get --prn $DEVICE_PRN
Verify peridiod is running on device:
systemctl status peridiod
journalctl -u peridiod -n 50
Test outbound connectivity from device:
# On device
curl -v https://api.peridio.com
nc -zv tunnel.peridio.com 443
Connection Refused
Symptoms:
ssh: connect to host x.x.x.x port xxxxx: Connection refused
- Browser shows "Unable to connect"
Possible Causes:
- Service not running on device
- Wrong port specified
- Firewall blocking connection
Solutions:
Verify service is running:
# For SSH
systemctl status sshd
netstat -tlnp | grep :22
# For HTTP service
netstat -tlnp | grep :80
curl http://localhost:80
Check firewall rules:
iptables -L -n
ufw status
Authentication Failures
Symptoms:
Permission denied (publickey,password)
- HTTP 401 Unauthorized errors
Solutions:
For SSH authentication:
# Check SSH configuration
grep -E "PasswordAuthentication|PubkeyAuthentication" /etc/ssh/sshd_config
# Verify user exists
id username
# Check authorized_keys permissions
ls -la ~/.ssh/
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
Tunnel Expires Too Quickly
Symptoms:
- Tunnel closes before work is complete
- Frequent reconnection needed
Solutions:
Request longer duration:
peridio tunnels create \
--device-prn $DEVICE_PRN \
--device-tunnel-port 22 \
--expires-in 7200 # 2 hours
Keep connection alive:
# SSH keep-alive
ssh -o ServerAliveInterval=60 \
-o ServerAliveCountMax=10 \
user@server_ip -p server_port
Slow Connection Performance
Symptoms:
- High latency
- Slow file transfers
- Timeouts
Solutions:
Check network metrics:
# Ping test
ping -c 10 server_ip
# Bandwidth test
iperf3 -c server_ip -p server_port
# MTU issues
ping -M do -s 1472 server_ip
Optimize SSH for slow connections:
ssh -C -o Compression=yes \
-o CompressionLevel=9 \
user@server_ip -p server_port
Diagnostic Commands
Device-Side Diagnostics
#!/bin/bash
# device-diagnostics.sh
echo "=== System Information ==="
uname -a
uptime
echo "=== Network Configuration ==="
ip addr show
ip route show
cat /etc/resolv.conf
echo "=== Peridiod Status ==="
systemctl status peridiod
journalctl -u peridiod -n 20
echo "=== Connection Test ==="
curl -v https://api.peridio.com/health
ping -c 3 8.8.8.8
echo "=== Firewall Status ==="
iptables -L -n
Client-Side Diagnostics
#!/bin/bash
# client-diagnostics.sh
TUNNEL_PRN=$1
echo "=== Tunnel Information ==="
peridio tunnels get --prn $TUNNEL_PRN
echo "=== Network Path ==="
traceroute server_ip
echo "=== Port Connectivity ==="
nc -zv server_ip server_port
echo "=== DNS Resolution ==="
nslookup server_ip
Error Messages
"Device not found"
Error: Device with PRN prn:1:device:xxx not found
Solution:
- Verify device PRN is correct
- Check device exists:
peridio devices list
- Ensure you have permissions for the device
"Tunnel creation failed"
Error: Failed to create tunnel: Maximum tunnels exceeded
Solution:
- Close existing tunnels:
peridio tunnels delete --prn $TUNNEL_PRN
- Check tunnel quota limits
- Wait for expired tunnels to close automatically
"Network unreachable"
ssh: connect to host x.x.x.x port xxxxx: Network is unreachable
Solution:
- Check local network connectivity
- Verify DNS resolution
- Try using IP address directly
Performance Optimization
SSH Multiplexing
Reuse SSH connections:
# ~/.ssh/config
Host tunnel-*
ControlMaster auto
ControlPath ~/.ssh/cm-%r@%h:%p
ControlPersist 10m
Compression Settings
For slow connections:
# SSH compression
ssh -C user@server_ip -p server_port
# SCP with compression
scp -C -P server_port file.txt user@server_ip:/tmp/
Buffer Tuning
Optimize TCP buffers:
# On device
echo 'net.core.rmem_max = 134217728' >> /etc/sysctl.conf
echo 'net.core.wmem_max = 134217728' >> /etc/sysctl.conf
echo 'net.ipv4.tcp_rmem = 4096 87380 134217728' >> /etc/sysctl.conf
echo 'net.ipv4.tcp_wmem = 4096 65536 134217728' >> /etc/sysctl.conf
sysctl -p
Debugging Tools
Verbose SSH Connection
ssh -vvv user@server_ip -p server_port
Network Packet Capture
# Capture tunnel traffic
tcpdump -i any -w tunnel.pcap host server_ip
# Analyze with Wireshark
wireshark tunnel.pcap
Connection State Monitoring
# Monitor connection states
watch -n 1 'netstat -an | grep server_port'
# Track bandwidth usage
iftop -P -n -f "host server_ip"
Recovery Procedures
Stuck Tunnel Cleanup
#!/bin/bash
# cleanup-stuck-tunnels.sh
# Find tunnels older than 1 hour in created state
STUCK_TUNNELS=$(peridio tunnels list \
--state created \
--output json | \
jq -r '.tunnels[] |
select(.created_at < (now - 3600)) |
.prn')
for tunnel in $STUCK_TUNNELS; do
echo "Cleaning up stuck tunnel: $tunnel"
peridio tunnels delete --prn $tunnel
done
Device Recovery
If device becomes unresponsive:
- Restart peridiod service:
systemctl restart peridiod
- Clear peridiod cache:
rm -rf /var/cache/peridiod/*
systemctl restart peridiod
- Re-register device if necessary:
peridiod --register --key device.key
Getting Help
Collecting Debug Information
When reporting issues, include:
# Create debug bundle
#!/bin/bash
DEBUG_DIR="tunnel-debug-$(date +%Y%m%d-%H%M%S)"
mkdir $DEBUG_DIR
# Collect tunnel info
peridio tunnels get --prn $TUNNEL_PRN > $DEBUG_DIR/tunnel.json
# Device info
peridio devices get --prn $DEVICE_PRN > $DEBUG_DIR/device.json
# Network diagnostics
traceroute server_ip > $DEBUG_DIR/traceroute.txt
ping -c 10 server_ip > $DEBUG_DIR/ping.txt
# Create archive
tar -czf $DEBUG_DIR.tar.gz $DEBUG_DIR/
echo "Debug bundle created: $DEBUG_DIR.tar.gz"
Support Channels
- GitHub Issues: Report bugs
- Documentation: Peridio Docs
- Community Forum: Get help from the community
Next Steps
- Security Best Practices - Prevent security issues
- Getting Started - Basic setup guide
- API Reference - Complete API documentation