SSHPiper 1.6.1

Option A: AWS Marketplace console

• Open the SecureAnyCloud Hardened WireGuard VPN & VPN, Proxy and Remote Access AMIs listing on AWS Marketplace. Choose View purchase options, then Subscribe. One subscription covers every version in the listing.
• When the subscription is active, choose Launch your software.
• Choose One-click launch from AWS Marketplace (or Launch from EC2 Console for the full launch wizard). In Version, choose SSHPiper 1.6.1 on Ubuntu 24.04, then choose your Region.
• Pick an instance type and your key pair. m5.large is recommended, and the software charge is $0.04 per vCPU per hour.
• Set the security group. The listing's default group opens ports 22 and 2222. Restrict port 22 to your own IP address, and restrict port 2222 to the networks your users connect from.
• Choose a subnet in the VPC where your upstream SSH servers live. Leave the metadata defaults, because the image already requires IMDSv2. Then choose Launch.

Option B: AWS CLI

Run this on your own workstation. It creates a security group, then launches the instance. Replace the AMI ID with the one shown for your Region on the Marketplace launch page. Replace the VPC, subnet, key pair and CIDR ranges with your own.

SG=$(aws ec2 create-security-group --group-name sshpiper \
  --description "SSHPiper gateway" --vpc-id vpc-0123456789abcdef0 \
  --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 22 --cidr <your-mgmt-cidr>
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 2222 --cidr <your-client-cidr>
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key-pair \
  --security-group-ids "$SG" \
  --subnet-id subnet-0123456789abcdef0 \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=sshpiper}]'

You do not need --metadata-options, because the AMI already requires IMDSv2. The upstream servers' security groups must allow SSH from this instance's security group.

Connect over SSH as ubuntu with the key pair you chose:

ssh -i ~/.ssh/my-key-pair.pem ubuntu@<public-ip>

First boot finishes within a minute of launch. It generates the four keys, starts the demo upstream and sshpiperd, and checks that the demo pipe works.

The details are in /root/sshpiper-credentials.txt, which only root can read. The file holds fingerprints and the connect command, not key material. Print it with sudo:

sudo cat /root/sshpiper-credentials.txt

# SSHPiper 1.6.1 - written by sshpiper-firstboot on this instance. No key material is stored in this file.
# Demo client key (private half): /root/sshpiper-demo-key (0600 root). Copy it to your client machine, then shred it here.
# Try the demo pipe:
ssh -p 2222 -i <demo key> demo@203.0.113.10 -> lands on demobackend@127.0.0.1:2200
# Your own upstreams: /etc/sshpiper/sshpiperd.yaml (authorise /etc/sshpiper/upstream/id_ed25519.pub on each upstream host). Self-test:
sudo sshpiper-selftest
# Guide: https://secureanycloud.com/stacks/sshpiper-1-6-1/ SSHPIPER_HOST=203.0.113.10 SSHPIPER_PORT=2222 SSHPIPER_DEMO_USER=demo SSHPIPER_DEMO_KEY_FILE=/root/sshpiper-demo-key SSHPIPER_DEMO_KEY_FINGERPRINT=SHA256:Jq3vT8nW1cY6pL0aR5dK2mX9sH4fB7gE3uZ1oN8iQw4 SSHPIPER_HOST_KEY_FINGERPRINT=SHA256:or4eT9kU2pV6bN1xS7tM3cL8dG0hJ5aY2fW4iQ7zRq0 SSHPIPER_UPSTREAM_PUBLIC_KEY_FILE=/etc/sshpiper/upstream/id_ed25519.pub SSHPIPER_UPSTREAM_KEY_FINGERPRINT=SHA256:Pz6wQ1eR8tY3uI5oA9sD2fG7hJ4kL0zX6cV1bN3mWe2 SSHPIPER_DEMO_UPSTREAM=demobackend@127.0.0.1:2200 SSHPIPER_DEMO_UPSTREAM_HOST_KEY_FINGERPRINT=SHA256:Lm2nB5vC8xZ1aS4dF7gH0jK3qW6eR9tY2uI5oP8lKj1

Your values will differ, because every instance has its own keys.

Check that the three services are active and see which ports are listening:

systemctl is-active sshpiper sshpiper-demo-backend sshpiper-firstboot
sudo ss -Htlnp | awk '{print $4, $6}'

active active active 127.0.0.1:2200 users:(("sshd",pid=9539,fd=3)) 127.0.0.53%lo:53 users:(("systemd-resolve",pid=404,fd=15)) 0.0.0.0:22 users:(("sshd",pid=891,fd=3),("systemd",pid=1,fd=175)) 127.0.0.54:53 users:(("systemd-resolve",pid=404,fd=17)) [::]:22 users:(("sshd",pid=891,fd=4),("systemd",pid=1,fd=176)) *:2222 users:(("sshpiperd",pid=9585,fd=3))

sshpiperd owns port 2222. The system SSH server keeps port 22 for administration. The demo upstream listens on loopback only, and nothing else listens on the network.

Run the self-test on the instance. It connects through sshpiperd with the demo key and checks that:

• the host key on port 2222 is this instance's key
• the pipe lands on the demo upstream
• an unknown key, users without a pipe and password logins are all refused
• ssh -W through the pipe reaches neither the metadata service nor any other address

sudo sshpiper-selftest

[sshpiper-selftest] host key pinned; demo -> sshpiperd:2222 -> demobackend@127.0.0.1:2200 (the upstream sees 127.0.0.1) [sshpiper-selftest] an unauthorized key is refused [sshpiper-selftest] users without a pipe (root, demobackend, ubuntu, nosuchpipe) are refused [sshpiper-selftest] password authentication is refused (offered: publickey) [sshpiper-selftest] ssh -W through the pipe reaches neither the metadata service nor any other address (forwarding refused) SELFTEST_OK

On the instance, pin the host key of sshpiperd and log in as demo with the demo key:

printf '[127.0.0.1]:2222 %s\n' "$(sudo cut -d' ' -f1,2 /etc/sshpiper/ssh_host_ed25519_key.pub)" > /tmp/sshpiper_known_hosts
sudo ssh -p 2222 -i /root/sshpiper-demo-key -o UserKnownHostsFile=/tmp/sshpiper_known_hosts demo@127.0.0.1

Pseudo-terminal will not be allocated because stdin is not a terminal. sac-sshpiper-demo: you are demobackend on the demo upstream sshd (127.0.0.1:2200 on ip-172-31-88-77), reached through sshpiperd sac-sshpiper-demo: this upstream sees the connection from 127.0.0.1 (sshpiperd), not from your client sac-sshpiper-demo: it runs no commands; route sshpiperd to your own hosts in /etc/sshpiper/sshpiperd.yaml

You logged in as demo and arrived as demobackend on the upstream. sshpiperd authenticated you with the demo key, then logged in to the upstream with its own upstream key. The demo upstream only prints these lines and runs no command you send.

To try it from your workstation, copy the demo key off the instance. Run this on your workstation:

umask 077 ssh -i ~/.ssh/my-key-pair.pem ubuntu@<SSHPIPER_HOST> 'sudo cat /root/sshpiper-demo-key' > ~/.ssh/sshpiper-demo-key ssh -p 2222 -i ~/.ssh/sshpiper-demo-key demo@<SSHPIPER_HOST>

The first time you connect, SSH shows the gateway's host key fingerprint. Accept it only if it equals SSHPIPER_HOST_KEY_FINGERPRINT in the credentials file. After you have your copy, remove the server's copy of the demo key:

sudo shred -u /root/sshpiper-demo-key

Each pipe maps one downstream login name to an upstream server. The example below routes the user alice to her real server at 10.0.1.20.

• Authorize the gateway on the upstream server. sshpiperd logs in to upstream servers with this instance's upstream key. Print its public half:

bash sudo cat /etc/sshpiper/upstream/id_ed25519.pub

Add that line to ~/.ssh/authorized_keys of the account that sshpiperd should log in as on 10.0.1.20 (here alice).

• Pin the upstream server's host key and install Alice's public key on the gateway. Copy her id_ed25519.pub to the instance first:

bash sudo install -d -o root -g sshpiper -m 0750 /etc/sshpiper/users/ ssh-keyscan -p 22 -t ed25519 10.0.1.20 | sudo tee /etc/sshpiper/users/10.0.1.20.known_hosts sudo install -o root -g sshpiper -m 0640 alice.pub /etc/sshpiper/users/alice.pub sudo chown root:sshpiper /etc/sshpiper/users/10.0.1.20.known_hosts && sudo chmod 0640 /etc/sshpiper/users/10.0.1.20.known_hosts

Compare the fingerprint that ssh-keyscan returned with the one the upstream server's administrator gives you. The administrator can print it with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on that server.

• Add the pipe to /etc/sshpiper/sshpiperd.yaml under pipes:. Open the file with sudo nano /etc/sshpiper/sshpiperd.yaml.

yaml - from: - username: "alice" authorized_keys: /etc/sshpiper/users/alice.pub to: host: 10.0.1.20:22 username: "alice" private_key: /etc/sshpiper/upstream/id_ed25519 known_hosts: /etc/sshpiper/users/10.0.1.20.known_hosts

• Restart sshpiperd, then connect as Alice from her machine:

bash sudo systemctl restart sshpiper ssh -p 2222 -i ~/.ssh/id_ed25519 alice@<SSHPIPER_HOST>

Every file the configuration names must be owned by root and readable by the sshpiper group but not by others (root:sshpiper, mode 0640). Otherwise sshpiperd refuses to start (see "How the secure start works").

The client chooses only the login name. The upstream address, account and key always come from this file, and a login name without a pipe is refused. The full syntax of the YAML router (several users per pipe, regular-expression user names, user CA keys) is described in /usr/local/share/doc/sshpiper/yaml-plugin-README.md.

When your own pipes work, remove the demo. First delete the demo pipe from /etc/sshpiper/sshpiperd.yaml. That is the - from: entry for username: "demo" and its to: block. Then restart sshpiperd, stop the demo upstream and shred its keys:

sudo systemctl restart sshpiper
sudo systemctl disable --now sshpiper-demo-backend
sudo shred -u /root/sshpiper-demo-key /etc/sshpiper/demo/authorized_keys /etc/sshpiper/upstream/demo-backend.known_hosts

Keep /etc/sshpiper/upstream/id_ed25519. It is the key sshpiperd uses for your own upstream servers. Disabling the demo upstream does not affect sshpiperd.

List the most recent pipes that sshpiperd created:

sudo journalctl -u sshpiper --no-pager -o cat | grep 'pipe created' | tail -3

time=2026-10-31T20:43:04.376Z level=INFO msg="ssh connection pipe created" downstream_addr=198.51.100.7:44852 downstream_user=demo upstream_addr=127.0.0.1:2200 upstream_user=demobackend

sshpiperd logs every pipe with the real client address (downstream_addr) and the upstream it chose.

The upstream server, however, sees the connection come from the gateway, not from the client. Its own logs, fail2ban, AllowUsers user@address rules and other per-address controls all see this instance's private address. Apply per-client address controls on the gateway (its security group, or the from: side of a pipe) rather than on the upstream servers. Keep the upstream servers' SSH reachable only from the gateway.