Update README.md
This commit is contained in:
parent
30c6a3cbdf
commit
434eaada9e
1 changed files with 189 additions and 2 deletions
191
README.md
191
README.md
|
|
@ -1,3 +1,190 @@
|
|||
# ssh-tunneling
|
||||
# SSH Tunneling Script
|
||||
|
||||
SSH Tunneling: Creating Bi-directional Remote Access Through NAT
|
||||
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.
|
||||
Loading…
Reference in a new issue