Quick Start and Building

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• cmd/sshpiperd/main.go
• cmd/sshpiperd-webadmin/internal/httpapi/web/README.md
• plugin/workingdir/main.go
• plugin/lua/README.md

SSHPiper is a specialized reverse proxy for SSH that enables complex routing logic between downstream clients and upstream servers. It supports various protocols layered over SSH, including SCP and port forwarding. The system is designed around a modular architecture where a core daemon (sshpiperd) manages connections while external plugins handle routing and authentication mapping.

Sources: README.md:1-12, CONTRIBUTING.md:52-57

Development Environment Setup

To begin working with SSHPiper, several software prerequisites must be met, primarily centered around the Go toolchain and Docker for containerized testing.

Software Requirements

• Go: https://go.dev/
• Docker & Docker Compose: https://www.docker.com/
• Git: https://git-scm.com/

Sources: CONTRIBUTING.md:8-13

Getting the Source

Cloning the repository requires initializing submodules to ensure all internal libraries (such as the seasoned crypto SSH lib) are available.

git clone https://github.com/tg123/sshpiper
cd sshpiper
git submodule update --init --recursive

Sources: CONTRIBUTING.md:15-21

Building the Project

Core Daemon and Plugins

The project uses Go build tags to include full functionality. The standard build process creates binaries in an output directory.

mkdir out
go build -tags full -o out ./...

Sources: README.md:46-52

Web Admin Frontend

The sshpiperd-webadmin component includes a vanilla JavaScript frontend that must be compiled using Node.js before being embedded into the Go binary.

1. Navigate to cmd/sshpiperd-webadmin/internal/httpapi/web/.
2. Run npm ci to install dependencies.
3. Run npm run build to generate the dist/ files.

The Go compiler uses //go:embed to include the resulting app.js and app.css into the final executable.

Sources: cmd/sshpiperd-webadmin/internal/httpapi/web/README.md:20-35

Quick Start Demo

A simple demonstration involves running a dummy SSH server and proxying a connection through sshpiperd using the fixed plugin.

1. Start Upstream Server

docker run -d -e USER_NAME=user -e USER_PASSWORD=pass -e PASSWORD_ACCESS=true -p 127.0.0.1:5522:2222 lscr.io/linuxserver/openssh-server

2. Start SSHPiperd

The daemon requires a server key. It can be configured to generate one if it does not exist.

./out/sshpiperd -i /tmp/sshpiperkey --server-key-generate-mode notexist --log-level=trace ./out/fixed --target 127.0.0.1:5522

3. Connect

ssh 127.0.0.1 -l user -p 2222

Sources: README.md:54-72

Architectural Overview

The following diagram illustrates the data flow from a downstream client through the piper to an upstream server, highlighting the role of plugins in the authentication process.

The sshpiperd daemon wraps the crypto/ssh library. Plugins communicate via gRPC, typically over stdin/stdout using a wrapper, or via remote gRPC connections.

Sources: CONTRIBUTING.md:52-67, README.md:14-25

Configuration Options

Daemon Flags

The core daemon sshpiperd accepts numerous flags for network and security configuration.

Flag	Default	Description
--address, -l	0.0.0.0	Listening address for SSH connections.
--port, -p	2222	Listening port.
--server-key, -i	/etc/ssh/...	Path to server host keys.
--login-grace-time	30s	Timeout for establishing the pipe.
--admin-grpc-port	0	Port for the admin API (disabled if 0).

Sources: cmd/sshpiperd/main.go:121-160

Plugin Execution Logic

SSHPiperd supports chaining multiple plugins using a -- separator. For example, an "additional challenge" plugin (like simplemath) can be placed before a routing plugin (like fixed).

sshpiperd [options] ./out/simplemath -- ./out/fixed --target 127.0.0.1:5522

Sources: README.md:74-78, cmd/sshpiperd/main.go:117-119

Testing and Verification

E2E Environment

Developers can spin up a complete end-to-end testing environment using Docker Compose located in the e2e folder.

cd e2e
SSHPIPERD_DEBUG=1 docker-compose up --build -d

This environment provides two sshd instances:

• host-password:2222 (user/pass auth)
• host-publickey:2222 (public key auth)

Running Tests

After making changes, tests can be executed inside the testrunner container:

docker exec -ti e2e-testrunner-1 bash
cd /src/e2e
go test

Sources: CONTRIBUTING.md:25-45

Summary

Building SSHPiper requires a Go environment with submodule support. The project is highly modular, requiring separate build steps for the web admin frontend if UI modifications are made. Deployment involves running the sshpiperd daemon alongside at least one routing plugin, which can be verified using the provided Docker-based E2E testing suite.