Quick Start Guide¶

Get up and running with SSH Tools Suite in just a few minutes!

Installation Options¶

Option 1: Standalone Executable (Fastest)¶

Download: Go to GitHub Releases
Extract: Download and extract SSH-Tunnel-Manager-v1.0.9-Windows.zip
Run: Double-click SSH-Tunnel-Manager.exe

Option 2: PyPI Installation¶

# Install from PyPI (recommended for Python users)
pip install ssh-tools-suite==1.0.9

# Verify installation
ssh-tunnel-manager --version

Launch the Application¶

Using Standalone Executable¶

# Windows: Navigate to extracted folder and run
SSH-Tunnel-Manager.exe

# Or from command line with options
SSH-Tunnel-Manager.exe --help

Using PyPI Installation¶

GUI Application:

# Method 1: Using the installed script
ssh-tunnel-manager-gui

# Method 2: Using Python module
python -m ssh_tunnel_manager.gui

# Method 3: Direct execution (if in source directory)
python ssh_tunnel_manager_app.py

Command Line Interface:

# View available commands
ssh-tunnel-manager --help

# List configurations
ssh-tunnel-manager list

# Start a specific tunnel
ssh-tunnel-manager start tunnel_name

Creating Your First Tunnel¶

Step 1: Open the Configuration Dialog¶

Launch the SSH Tunnel Manager GUI
Click the "Add Tunnel" button (➕) in the toolbar
The Tunnel Configuration Dialog will open

Step 2: Basic Configuration¶

Fill in the essential information:

Name: camera_access
Description: Access to IP camera via SSH tunnel

Step 3: SSH Connection Settings¶

Configure the SSH connection:

SSH Host: 192.168.1.100    # Your SSH server IP/hostname
SSH Port: 22               # SSH port (usually 22)
SSH User: admin            # Your SSH username
SSH Key Path: (optional)   # Leave blank to use password

Step 4: Tunnel Settings¶

Set up the port forwarding:

Tunnel Type: Local
Local Port: 8554           # Port on your computer
Remote Host: localhost     # Target host (from SSH server perspective)
Remote Port: 554           # Target port on remote host

Step 5: Save and Test¶

Click "OK" to save the configuration
Select your new tunnel in the main table
Click "Start" (▶️) to establish the tunnel
Click "Test" (🧪) to verify connectivity

Common Tunnel Types¶

Local Port Forwarding (Most Common)¶

Use case: Access a service on a remote network through an SSH server

Type: Local
Local Port: 8080
Remote Host: localhost (or internal IP)
Remote Port: 80

Result: http://localhost:8080 → Remote server's port 80

Remote Port Forwarding¶

Use case: Allow remote users to access your local service

Type: Remote
Local Port: 3000
Remote Host: localhost
Remote Port: 8080

Result: Remote users can access your port 3000 via SSH server's port 8080

Dynamic Port Forwarding (SOCKS Proxy)¶

Use case: Route all traffic through the SSH server

Type: Dynamic
Local Port: 1080

Result: Configure applications to use SOCKS proxy localhost:1080

Example Configurations¶

RTSP Camera Access¶

Name: ip_camera_rtsp
SSH Host: router.example.com
SSH Port: 22
SSH User: admin
Tunnel Type: Local
Local Port: 8554
Remote Host: 192.168.1.50
Remote Port: 554
RTSP URL: rtsp://localhost:8554/live/0

Web Interface Access¶

Name: router_admin
SSH Host: router.example.com
SSH Port: 22
SSH User: admin
Tunnel Type: Local
Local Port: 8080
Remote Host: localhost
Remote Port: 80

Database Connection¶

Name: mysql_dev
SSH Host: db-server.company.com
SSH Port: 22
SSH User: developer
Tunnel Type: Local
Local Port: 3307
Remote Host: localhost
Remote Port: 3306

Using SSH Keys (Recommended)¶

Generate SSH Key Pair¶

# Generate a new SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"

# Or RSA if ed25519 isn't supported
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Deploy Key to Server¶

# Copy public key to server
ssh-copy-id user@hostname

# Or manually copy the public key content
cat ~/.ssh/id_ed25519.pub
# Paste into server's ~/.ssh/authorized_keys

Configure in SSH Tunnel Manager¶

In the tunnel configuration dialog
Set SSH Key Path to your private key file:
Windows: C:\Users\YourName\.ssh\id_ed25519
Linux/macOS: /home/username/.ssh/id_ed25519

Testing Your Tunnel¶

Using the Built-in Tester¶

Select your tunnel in the main table
Click "Start" to establish the connection
Click "Test" to verify connectivity
Check the log output for results

Manual Testing¶

Test Port Connectivity¶

# Test if the local port is listening
netstat -an | grep :8554    # Linux/macOS
netstat -an | findstr :8554 # Windows

# Test connection
telnet localhost 8554

Test HTTP Services¶

# Using curl
curl http://localhost:8080

# Using browser
# Navigate to http://localhost:8080

Test RTSP Streams¶

# Using ffplay (if available)
ffplay rtsp://localhost:8554/live/0

# Using VLC
vlc rtsp://localhost:8554/live/0

Managing Multiple Tunnels¶

Auto-Start Configuration¶

Edit an existing tunnel configuration
Check "Auto-start on application launch"
The tunnel will start automatically when you open the application

Import/Export Configurations¶

# Export all configurations
File → Export Configurations → Save as tunnels.json

# Import configurations
File → Import Configurations → Select tunnels.json

Backup Your Settings¶

Configuration files are stored in: - Windows: %APPDATA%\SSHTunnelManager\ - Linux: ~/.config/SSHTunnelManager/ - macOS: ~/Library/Preferences/SSHTunnelManager/

System Tray Integration¶

The SSH Tunnel Manager can run in the system tray:

Minimize to Tray: Close the main window (tunnel processes continue)
Quick Access: Right-click tray icon for menu options
Status Indicators: Tray icon shows overall tunnel status

Troubleshooting Quick Fixes¶

"Connection Refused"¶

Verify SSH server is running and accessible
Check firewall settings on both client and server
Confirm SSH port (usually 22) is correct

"Permission Denied"¶

Verify username and authentication method
Check SSH key permissions (should be 600)
Ensure user has SSH access on the server

"Port Already in Use"¶

Change the local port number

Kill any processes using the port:

# Linux/macOS
lsof -i :8554
kill -9 <PID>

# Windows
netstat -ano | findstr :8554
taskkill /PID <PID> /F

"Tunnel Not Working"¶

Verify the tunnel is in "running" status
Check that remote host/port are correct

Test from the SSH server directly:

ssh user@hostname
telnet localhost 554  # Test target service

Next Steps¶

Now that you have your first tunnel working:

Learn Advanced Features - Explore more tunnel types
RTSP Streaming Guide - Set up video streaming
SSH Key Management - Secure authentication
Configuration Management - Organize your tunnels

Need Help?¶

Documentation: Browse the full User Guides
Examples: Check the Usage Examples
Issues: Report problems on GitHub
Community: Join discussions in GitHub Discussions