SSH Tunneling Script

A robust bash script for managing SSH tunnels to enable bi-directional remote access through NAT networks. This script simplifies the process of setting up both reverse tunnels and local port forwarding with built-in logging, error handling, and automatic reconnection.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Network Architecture
• Troubleshooting
• Logging
• Security Considerations

Features

• ✨ Bi-directional tunneling support
• 🔄 Automatic retry on connection failure
• 📝 Comprehensive logging system
• 🎨 Colorized console output
• 🔒 Connection testing and validation
• 💪 Robust error handling
• 🔌 Clean shutdown management
• ⚡ Keepalive connection maintenance

Prerequisites

• Linux/Unix-based system
• SSH client installed
• netcat (nc) for port checking
• SSH access to a public-facing server
• Proper SSH key setup (recommended)

Installation

1. Download the script:

curl -O https://your-domain.com/tunnel.sh

2. Make it executable:

chmod +x tunnel.sh

3. Move to a suitable location:

sudo mv tunnel.sh /usr/local/bin/tunnel.sh

Configuration

Edit the following variables at the top of the script according to your setup:

SSHD_ADDRESS="user@example.com"      # Public SSH server address
REMOTE_ADDRESS="192.168.1.100"       # Remote computer's internal IP
LOCAL_RDP_PORT="3389"                # Local RDP port
REMOTE_RDP_PORT="3389"               # Remote RDP port
TUNNEL_PORT="2222"                   # Tunnel port on public server
SOCKS_PORT="8765"                    # Local SOCKS proxy port
LOG_FILE="/var/log/ssh-tunnel.log"   # Log file location
KEEP_ALIVE="60"                      # SSH keepalive interval in seconds
MAX_RETRIES=3                        # Maximum number of connection retries

Usage

The script supports two modes of operation:

1. Reverse Tunnel with SOCKS Proxy

Run on the local computer to allow incoming connections and set up SOCKS proxy:

./tunnel.sh reverse

2. Local Port Forwarding

Run on the local computer to access remote services:

./tunnel.sh local

Running as a Service

To run the script as a system service, create a systemd service file:

[Unit]
Description=SSH Tunnel Service
After=network.target

[Service]
ExecStart=/usr/local/bin/tunnel.sh reverse
Restart=always
User=your-username

[Install]
WantedBy=multi-user.target

Save as /etc/systemd/system/ssh-tunnel.service and enable:

sudo systemctl enable ssh-tunnel
sudo systemctl start ssh-tunnel

Network Architecture

The script is designed for the following network setup:

[Local Computer]  -->  [NAT]  -->  [Public SSH Server]  -->  [NAT]  -->  [Remote Computer]

• Local Computer: Behind NAT, runs the script
• Public SSH Server: Internet-facing server with SSH access
• Remote Computer: Behind NAT, target for remote access

Troubleshooting

Common Issues

1. Connection Refused

   • Check SSH server is running
   • Verify firewall rules
   • Ensure ports are not in use

2. Permission Denied

   • Verify SSH key setup
   • Check user permissions
   • Review SSH server configuration

3. Tunnel Fails to Establish

   • Check network connectivity
   • Verify port availability
   • Review SSH server logs

Debug Mode

Run with debug output:

ssh -vv [your normal parameters]

Logging

Logs are stored in /var/log/ssh-tunnel.log by default. The log includes:

• Connection attempts
• Tunnel establishment status
• Error messages
• Retry attempts

Example log output:

2024-12-06 10:15:23 [INFO] Testing SSH connection to user@example.com...
2024-12-06 10:15:24 [INFO] Setting up reverse tunnel and SOCKS proxy...
2024-12-06 10:15:25 [INFO] Reverse tunnel established (PID: 1234)

Security Considerations

1. SSH Keys

   • Use SSH keys instead of passwords
   • Protect private keys with strong passphrases
   • Regularly rotate SSH keys

2. Port Selection

   • Avoid well-known ports
   • Use high-numbered ports (>1024)
   • Consider port knocking

3. Access Control

   • Restrict SSH access by IP
   • Use AllowUsers in SSH config
   • Implement fail2ban

4. Server Configuration

   # /etc/ssh/sshd_config
   GatewayPorts clientspecified
   AllowTcpForwarding yes
   

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.