ssh-tunneling/README.md

# 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](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Network Architecture](#network-architecture)
- [Troubleshooting](#troubleshooting)
- [Logging](#logging)
- [Security Considerations](#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:
```bash
curl -O https://your-domain.com/tunnel.sh
```

2. Make it executable:
```bash
chmod +x tunnel.sh
```

3. Move to a suitable location:
```bash
sudo mv tunnel.sh /usr/local/bin/tunnel.sh
```

## Configuration

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

```bash
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:
```bash
./tunnel.sh reverse
```

### 2. Local Port Forwarding
Run on the local computer to access remote services:
```bash
./tunnel.sh local
```

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

```ini
[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:
```bash
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:
```bash
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**
   ```bash
   # /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](LICENSE) file for details.