197 lines
4.1 KiB
Markdown
197 lines
4.1 KiB
Markdown
# 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
|