---
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.