mirror of
https://github.com/jthistlethwaite/ssh-pipeweasel.git
synced 2026-06-30 07:17:40 -04:00
Jason Thistlethwaite
97 lines
3.4 KiB
Markdown
97 lines
3.4 KiB
Markdown
---
|
|
title: ssh-pipeweasel - manage complicated SSH network paths with ease
|
|
author: Jason Thistlethwaite
|
|
tags:
|
|
- ssh
|
|
- vpn
|
|
- wireguard
|
|
- wip
|
|
modified: 2026-06-07T13:49:45-04:00
|
|
---
|
|
|
|
# ssh-pipeweasel
|
|
ssh-pipeweasel is a tool for making complicated SSH connections easier to manage.
|
|
|
|
I created it to handle situations where I need to connect to various hosts that aren't always accessible for the internet, particularly from my laptop, where multiple routes could be possible like LAN, a WireGuard tunnel, or something else.
|
|
|
|
## Standard Usage
|
|
- Modify ~/.ssh/config and add `ProxyCommand ~/.ssh/ssh-pipeweasel.sh %h` to `Host` declarations you want to use it with.
|
|
- **Recommended**:
|
|
- Add `ServerAliveInterval 60` and `ServerAliveCountMax 3` to any connections using ssh-pipeweasel
|
|
- Copy `proxyconfig.example.sh` to `~/.ssh/hosts.d/`, rename it to match your host, and then edit it to list the options for that host
|
|
- **Testing it:**
|
|
- `DEBUG=true ~/.ssh/ssh-pipeweasel.sh <yourhost>`
|
|
- The above should output the availability and latency of all configured routes to that host
|
|
- **Using it:**
|
|
- `ssh <yourhost>` and ssh-pipeweasel automatically works in the background, selecting the best path to reach your configured ssh server.
|
|
|
|
## Installation and Setup
|
|
```bash
|
|
# Create directory for host config files
|
|
mkdir -p ~/.ssh/hosts.d/
|
|
|
|
# Set secure, default permissions on .ssh directories
|
|
chmod 0700 ~/.ssh/ && chmod 0700 ~/.ssh/hosts.d/
|
|
|
|
# Put the pipeweasel in place and mark it executable
|
|
cp ./ssh-pipeweasel.sh ~/.ssh/
|
|
chmod +x ~/.ssh/ssh-pipeweasel.sh
|
|
```
|
|
|
|
### Example Config File
|
|
```sh
|
|
# Order does not matter; it automatically selects the lowest latency response
|
|
ENDPOINTS=(
|
|
"LAN|192.168.1.10|22"
|
|
"WireGuard|10.11.0.10|22"
|
|
"Public|mybastion.uplinklounge.com|9002"
|
|
)
|
|
```
|
|
The file should be named after the Host alias you used inside of `~/.ssh/config`
|
|
|
|
### Example ssh_config (`~/.ssh/config`) file entry
|
|
```
|
|
# Connection muxing is a must-have for me, but this section is not needed for
|
|
# ssh-pipeweasel to function
|
|
ControlMaster auto
|
|
ControlPersist 4800
|
|
ControlPath ~/.ssh/control/%r.%n.%p.sock
|
|
|
|
# List of hosts that use the pipeweasel
|
|
Host bastion, mgmt01, mgmt02, pve
|
|
ProxyCommand ~/.ssh/ssh-pipeweasel.sh %h
|
|
ServerAliveInterval 60
|
|
ServerAliveCountMax 3
|
|
|
|
# Host-specific configs like port forwards, username, which key to use, etc.
|
|
Host bastion
|
|
IdentityFile ~/.ssh/id_ecdsa
|
|
User jason
|
|
LocalForward 13307 localhost:3306
|
|
LocalForward 18081 localhost:8081
|
|
DynamicForward localhost:19011
|
|
LocalForward 2222 localhost:2222
|
|
TCPKeepAlive yes
|
|
ExitOnForwardFailure no
|
|
|
|
|
|
```
|
|
|
|
# Dependencies
|
|
ssh-pipeweasel has been tested and is known to work on Ubuntu Linux 26.04 LTS.
|
|
|
|
It's only dependencies are:
|
|
- netcat
|
|
- Test with netcat-openbsd 1.206, which comes with Ubuntu by default
|
|
- bash
|
|
- GNU Awk
|
|
- openssh, I would think obviously
|
|
|
|
# Disclaimer
|
|
This tool is released without any particular warranty or claim it's actually useful or safe to use for anything. I'm posting this just in case other people have the same headache I have and this helps them.
|
|
|
|
## License & Authorship
|
|
This project is authored exclusively by Jason Thistlethwaite. It is distributed under a custom, restricted license. Specific individuals and affiliated entities are strictly prohibited from using this software.
|
|
|
|
Please see the full [LICENSE.md](./LICENSE.md) file for complete details, provenance documentation, and restriction clauses.
|