sshtunnel/README.md

SSH Tunnel Manager

A Go-based command-line tool to manage SSH tunnels. This tool allows you to:

• List currently active SSH tunnels
• Start new SSH tunnels as background daemons
• Stop running SSH tunnels
• Monitor traffic statistics for SSH tunnels

Installation

go install git.mvl.sh/vleeuwenmenno/sshtunnel@latest

You can also install a specific version:

go install git.mvl.sh/vleeuwenmenno/sshtunnel@v1.0.0

Or clone this repository and build it yourself:

git clone https://git.mvl.sh/vleeuwenmenno/sshtunnel.git
cd sshtunnel
make
sudo make install

The build process will automatically include version information from git tags.

Uninstallation

For installation using go install, run:

go clean -i git.mvl.sh/vleeuwenmenno/sshtunnel

For manual installation, run:

sudo make uninstall

Usage

Showing version information

sshtunnel version

This will display the current version of sshtunnel along with build information.

Options:

• -c, --check-updates: Check for updates against the latest release

Listing active tunnels

sshtunnel list

This will display all active SSH tunnels with their IDs, local ports, remote endpoints, and process IDs.

Starting a new tunnel

sshtunnel start -l 8080 -r 80 -H example.com -s user@ssh-server.com

Options:

• -l: Local port to forward (required)
• -r: Remote port to forward to (required)
• -H: Remote host to forward to (default: "localhost")
• -s: SSH server address in the format user@host (required)
• -i: Path to SSH identity file (optional)

Stopping tunnels

Stop a specific tunnel by ID:

sshtunnel stop -i 1

Stop all active tunnels:

sshtunnel stop --all

Options:

• -i: ID of the tunnel to stop
• --all: Stop all tunnels

Viewing traffic statistics

View statistics for all tunnels:

sshtunnel stats --all

View statistics for a specific tunnel:

sshtunnel stats -i 1

Monitor tunnel traffic in real-time:

sshtunnel stats -i 1 --watch

Options:

• --id: ID of the tunnel to show statistics for
• --all: Show statistics for all tunnels
• --watch: Continuously monitor statistics (only with specific tunnel ID)
• --interval: Update interval in seconds for watch mode (default: 5)

Debugging tunnels

Run diagnostics to troubleshoot issues with SSH tunnels:

sshtunnel debug

This command will:

1. Check if SSH client is properly installed
2. Verify the tunnel directory exists and is accessible
3. Validate all recorded tunnels and their current state
4. Show active SSH tunnel processes and their status

Version information

sshtunnel version --check-updates

This displays version information and checks for updates to the tool.

When a new version is available, you'll get instructions on how to update.

Shell completion

Generate shell completion scripts:

# Bash
sshtunnel completion bash > ~/.bash_completion.d/sshtunnel
source ~/.bash_completion.d/sshtunnel

# Zsh
sshtunnel completion zsh > "${fpath[1]}/_sshtunnel"

# Fish
sshtunnel completion fish > ~/.config/fish/completions/sshtunnel.fish

For system-wide installation:

# Bash (Linux)
sudo sshtunnel completion bash > /etc/bash_completion.d/sshtunnel

# Bash (macOS with Homebrew)
sshtunnel completion bash > $(brew --prefix)/etc/bash_completion.d/sshtunnel

Development

Release Process

The project includes a release script to help manage version tags:

./bin/scripts/release.sh

This script will:

1. Find the latest version tag
2. Suggest the next patch version (e.g., v1.0.0 → v1.0.1)
3. Allow you to accept this suggestion or enter a custom version
4. Create and push the new tag
5. Update the "latest" tag to point to the new version

How it works

The tool creates SSH tunnels using the system's SSH client and manages them by tracking their process IDs in a hidden directory (~/.sshtunnels/). Each tunnel is assigned a unique ID for easy management. Traffic statistics are collected and stored to help you monitor data transfer through your tunnels.

Requirements

• Go 1.16 or higher
• SSH client installed on your system

License

MIT