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

# 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

# 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 file for complete details, provenance documentation, and restriction clauses.

3.4 KiB Raw Permalink Blame History