Troubleshooting¶

This guide helps you diagnose and resolve common issues with SSH Tunnel Manager.

SSH Connection Issues¶

Tunnel Cannot Establish Connection¶

Symptom: Tunnel fails to start or immediately disconnects.

Possible causes and solutions:

SSH key permissions are incorrect

Ensure the .ssh directory and its contents have appropriate permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/*.pub
chmod 644 ~/.ssh/config
chmod 644 ~/.ssh/known_hosts

SSH config file is missing or incorrect

Check if ~/.ssh/config file exists and is correctly configured:

cat ~/.ssh/config

Refer to SSH Configuration Guide for proper configuration.

Remote host is unreachable

Test SSH connection:

ssh user@remote-host

Firewall blocking connection

Check local and remote firewall settings to ensure SSH connections are allowed.

Permission Denied¶

Symptom: SSH connection prompts permission denied.

Solutions:

Confirm using the correct SSH key:

ssh -i ~/.ssh/id_ed25519 user@remote-host

Check the remote server's authorized_keys file:

cat ~/.ssh/authorized_keys  # Execute on remote server

Ensure public key is added to remote server:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@remote-host

Docker Issues¶

Container Won't Start¶

Symptom: docker compose up fails.

Solutions:

Check Docker service status:
```
sudo systemctl status docker
```

Check port conflicts:

# Check port 5000 (Web panel)
netstat -tuln | grep 5000

# Check port 8080 (API server)
netstat -tuln | grep 8080

View container logs:
```
docker compose logs
```

Docker Permission Issues¶

Symptom: Permission denied when running Docker commands.

Solutions:

Add user to docker group:
```
sudo usermod -aG docker $USER
```
Re-login or run:
```
newgrp docker
```

File Permission Issues¶

Symptom: Container cannot access mounted files.

Solutions:

Check PUID and PGID settings:
```
id  # View current user's UID and GID
```

Set correct values in compose.yaml:

environment:
  - PUID=1000  # Replace with your UID
  - PGID=1000  # Replace with your GID

Restart containers:

docker compose down
docker compose up -d

Configuration Issues¶

Configuration File Format Error¶

Symptom: Tunnel cannot start, logs show YAML parsing error.

Solutions:

Validate YAML syntax:

# Validate using Python
python3 -c "import yaml; yaml.safe_load(open('config/config.yaml'))"

Check common errors:
Indentation must use spaces, not tabs
Ensure there's a space after colons
String values with special characters need quotes
Reference sample configuration:
```
cat config/config.yaml.sample
```

Configuration Changes Not Taking Effect¶

Symptom: Tunnel not updated after modifying configuration.

Solutions:

Check if config file monitoring is working:

docker compose logs autossh | grep inotify

Manually restart service:
```
docker compose restart autossh
```

Verify config file path:

docker compose exec autossh cat /etc/autossh/config/config.yaml

Interactive Authentication Issues¶

Interactive Tunnel Won't Start¶

Symptom: Running autossh-cli auth <hash> fails or shows errors, or the in-browser terminal modal fails to connect.

Solutions:

Ensure using correct user context (CLI):

The auth command must be run as myuser user:

docker exec -it -u myuser <container_name> autossh-cli auth <hash>

Without -u myuser, you may see permission errors accessing SSH config files.

Verify tunnel is marked as interactive:

Check if the tunnel has interactive: true in config:

docker exec -it autossh-1 autossh-cli show-tunnel <hash>

Check SSH host configuration:

Ensure the remote host is properly configured in ~/.ssh/config:

docker exec -it autossh-1 cat /home/myuser/.ssh/config

WebSocket connection fails (in-browser terminal):

If the xterm.js terminal modal shows "Failed to connect to authentication server":

Verify WS_BASE_URL is set correctly on the web container:

docker compose exec web env | grep WS_BASE_URL

Verify the ws-server is running in the autossh container:
```
docker compose logs autossh | grep ws-server
```
Check that WS_PORT (default 8022) is accessible from the web container. When autossh uses network_mode: "host", use ws://localhost:8022.

Authentication Fails¶

Symptom: 2FA code or password is rejected.

Solutions:

Verify credentials:
Ensure you're entering the correct 2FA code or password
Check if the 2FA token has expired (TOTP codes are time-sensitive)
Check SSH server configuration:
Verify the remote server supports keyboard-interactive authentication
Check if your account is locked or disabled on the remote server

Test manual SSH connection:

docker exec -it -u myuser autossh-1 ssh <remote_host>

Interactive Tunnel Shows STOPPED After Authentication¶

Symptom: Tunnel authenticates successfully but immediately shows as STOPPED.

Solutions:

Check tunnel logs:

docker exec -it autossh-1 autossh-cli logs <hash>

Verify port availability:

Ensure the local/remote port is not already in use:

netstat -tuln | grep <port_number>

Check SSH control socket:

docker exec -it autossh-1 ls -la /tmp/ssh_control_*

Tunnel Runtime Issues¶

Tunnel Frequently Disconnects and Reconnects¶

Symptom: Tunnel is unstable, frequently disconnects.

Solutions:

Check network connection stability

Adjust autossh parameters:

environment:
  - AUTOSSH_GATETIME=30  # Increase connection stability time

Check remote server load and network conditions

Port Already in Use¶

Symptom: Tunnel fails to start, prompts port is in use.

Solutions:

Find process using the port:

# Linux
sudo lsof -i :port_number

# Or use
sudo netstat -tulpn | grep port_number

Stop the process using the port or change tunnel configuration to use a different port

Cannot Access Tunnel Service¶

Symptom: Tunnel shows running but cannot access service.

Solutions:

Check tunnel direction:
local_to_remote: Access on remote server
remote_to_local: Access on local machine

Verify port binding:

# Check port listening on the appropriate machine
netstat -tuln | grep port_number

Check firewall rules:

# View firewall status
sudo ufw status  # Ubuntu/Debian
sudo firewall-cmd --list-all  # CentOS/RHEL

Test connection:

# Local test
curl http://localhost:port_number

# Remote test
curl http://remote-host:port_number

Web Panel Issues¶

Cannot Access Web Panel¶

Symptom: Browser cannot open http://localhost:5000.

Solutions:

Check Web container status:
```
docker compose ps web
```
View Web container logs:
```
docker compose logs web
```
Verify port mapping:
```
docker compose port web 5000
```

Check API connection:

# Confirm API_BASE_URL is set correctly in compose.yaml
docker compose exec web env | grep API_BASE_URL

Web Panel Shows Blank or Error¶

Symptom: Web panel loads but displays abnormally.

Solutions:

Clear browser cache
Check browser console for errors (F12)
Verify API server is running:
```
curl http://localhost:8080/status
```

Symptom: Clicking Start/Restart on an interactive tunnel does not open the terminal modal.

Solutions:

Verify WS_BASE_URL is configured on the web container:

docker compose exec web env | grep WS_BASE_URL

Check that the web panel reports WebSocket as enabled:

curl http://localhost:5000/api/config/api
# Should show "ws_enabled": true

Verify the tunnel has interactive: true set in its configuration.

Symptom: The xterm.js terminal modal opens but displays an error message.

Solutions:

Check that the ws-server is running:

docker compose logs autossh | grep -i "ws-server\|websocket"

Verify the ws-server port is accessible:

# If autossh uses host network mode
curl -v http://localhost:8022

Ensure WS_BASE_URL uses the correct protocol (ws:// not http://) and port.

API Issues¶

API Request Fails¶

Symptom: CLI commands or HTTP API requests return errors.

Solutions:

Confirm API is enabled:
```
environment:
  - API_ENABLE=true
```
Check API server logs:
```
docker compose logs autossh | grep api
```
Test API connection:
```
curl http://localhost:8080/list
```

Logs and Debugging¶

Viewing Logs¶

# View all container logs
docker compose logs

# View specific container logs
docker compose logs autossh
docker compose logs web

# Follow logs in real-time
docker compose logs -f

# View last 100 lines of logs
docker compose logs --tail=100

Entering Container for Debugging¶

# Enter autossh container
docker compose exec autossh sh

# Enter web container
docker compose exec web sh

# Check processes inside container
ps aux

# Check network connections
netstat -tuln

Enable Verbose Logging¶

Add debug environment variables in compose.yaml:

environment:
  - DEBUG=true
  - VERBOSE=true

Performance Issues¶

Container Using Too Many Resources¶

Solutions:

Check resource usage:
```
docker stats
```

Limit container resources:

services:
  autossh:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

Clean up unused Docker resources:
```
docker system prune -a
```

Getting Help¶

If the above methods cannot solve your problem:

Check project documentation:
Getting Started
Architecture
API Documentation
Submit an Issue: Visit GitHub Issues to submit a problem
Provide information:
Operating system and version
Docker and Docker Compose versions
Complete error logs
Configuration file contents (hide sensitive information)
Steps to reproduce the problem

Troubleshooting¶

SSH Connection Issues¶

Tunnel Cannot Establish Connection¶

Permission Denied¶

Docker Issues¶

Container Won't Start¶

Docker Permission Issues¶

File Permission Issues¶

Configuration Issues¶

Configuration File Format Error¶

Configuration Changes Not Taking Effect¶

Interactive Authentication Issues¶

Interactive Tunnel Won't Start¶

Authentication Fails¶

Interactive Tunnel Shows STOPPED After Authentication¶

Tunnel Runtime Issues¶

Tunnel Frequently Disconnects and Reconnects¶

Port Already in Use¶

Cannot Access Tunnel Service¶

Web Panel Issues¶

Cannot Access Web Panel¶

Web Panel Shows Blank or Error¶

Terminal Modal Does Not Open¶

Terminal Modal Opens But Shows Connection Error¶

API Issues¶

API Request Fails¶

Logs and Debugging¶

Viewing Logs¶

Entering Container for Debugging¶

Enable Verbose Logging¶

Performance Issues¶

Container Using Too Many Resources¶

Getting Help¶