Rospo Documentation

Rospo is a single binary tool for creating secure SSH tunnels. It supports macOS, GNU/Linux, Windows 10+, and Docker.

macOS

Install via Homebrew:

brew install rospo

GNU/Linux

Download the appropriate binary from the GitHub releases page:

• amd64: https://github.com/ferama/rospo/releases/latest/download/rospo-linux-amd64
• arm64: https://github.com/ferama/rospo/releases/latest/download/rospo-linux-arm64
• arm: https://github.com/ferama/rospo/releases/latest/download/rospo-linux-arm

Microsoft Windows

Download the amd64 executable: https://github.com/ferama/rospo/releases/latest/download/rospo-windows-amd64.exe

Docker

Run the containerized version:

docker run ghcr.io/ferama/rospo --help

Rospo can be used via CLI for simple tasks or via a YAML configuration file for complex scenarios. It supports both key-based and password-based authentication (key-based is preferred).

Reverse Shell

Starts an embedded SSH server and reverse proxies a port (default 2222) to a remote server:

rospo revshell user@server:port

Tunneling

Forward a local port to a remote port on a remote server:

rospo tun forward -l :5000 -r :6000 user@server:port

Running with Configuration

For complex setups involving multiple tunnels, jump hosts, or SOCKS proxies, use a YAML config file:

rospo run config.yaml

Help

Get detailed help for specific subcommands:

rospo tun forward --help
rospo tun reverse --help
rospo sshd --help

You can install Rospo as a persistent Windows service to ensure tunnels start automatically with the machine. This requires Administrative privileges in PowerShell.

1. Create a configuration file

Example C:\conf.yaml for Remote Desktop (RDP):

sshclient:
  server: your-rospo-or-sshd-server-uri:2222
  identity: "c:\\absolute_path_to_your\\id_rsa"
  known_hosts: "C:\\absolute_path_to_your\\known_hosts"

tunnel:
  - remote: ":3389"
    local: ":3389"
    forward: false

2. Manage the service via sc.exe

Create the service:

sc.exe create rospo start= auto DisplayName= Rospo binpath= "C:\rospo.exe run C:\conf.yaml"

Start the service:

sc.exe start rospo

Check status:

sc.exe query rospo

Stop and delete the service:

sc.exe stop rospo; sc.exe delete rospo

To install rospo on macOS or Linux using Homebrew, first ensure Homebrew is installed, then use the brew install command.

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install rospo
brew install rospo

To run Rospo in an SSH daemon (sshd) mode using Docker Compose, follow these steps to prepare your keys and authorized users:

1. Generate server keys: Use the keygen command to create the necessary server keys.
2. Prepare authorized_keys: Create an authorized_keys file in your working directory to manage allowed SSH keys.
3. Start the container: Use docker compose to launch the service in detached mode.

Note: Ensure your docker-compose.yml is configured to mount the generated keys and the authorized_keys file into the container.

# 1. Generate keys
rospo keygen -n server_key -s

# 2. Create authorized_keys
touch authorized_keys

# 3. Run with docker compose
docker compose up -d

Rospo is a tool designed to create reliable SSH tunnels. It is invoked via the rospo command and requires at least one subcommand to function. If no valid subcommand is provided, the CLI will exit with an error.

# Basic usage requires a subcommand
rospo <subcommand> [args]

Rospo supports traversing multiple jump hosts to reach a target server. The resolution logic follows these rules:

1. SSH Config Integration: If you provide a --jump-host that matches a host entry in your local SSH configuration, Rospo will recursively resolve the ProxyJump chain defined in that config.
2. Identity Inheritance: As Rospo traverses the jump host chain, it uses the identity file associated with each host in the configuration.
3. Command Line Overrides: If you explicitly provide a flag (like --user-identity or --jump-host), the command line value takes precedence over values found in the SSH configuration file.
4. Final Hop: After resolving the chain from the SSH config, the final --jump-host provided on the command line is appended to the jump host list to complete the connection path.

You can deploy Rospo as a Docker container using a compose.yaml file. The service is configured to run in host network mode, which is necessary for Rospo to manage network connections as intended. The container requires a configuration file (/rospo.yaml) and several key files for authentication to be mounted as volumes.

services:
  rospo:
    restart: unless-stopped
    image: ghcr.io/ferama/rospo:main
    container_name: rospo
    command:
      - run
      - /rospo.yaml
    network_mode: "host"
    logging:
      driver: json-file
      options:
        max-size: "8m"
    volumes:
      - ./rospo.yaml:/rospo.yaml
      - ./server_key:/server_key
      - ./authorized_keys:/authorized_keys
      - ./server_key.pub:/server_key.pub

When running Rospo in Docker, the following volume mappings and command arguments are used to provide the necessary configuration and security credentials:

Required Volumes

• ./rospo.yaml:/rospo.yaml: The main Rospo configuration file.
• ./server_key:/server_key: The server's private key.
• ./server_key.pub:/server_key.pub: The server's public key.
• ./authorized_keys:/authorized_keys: The file containing authorized keys for access control.

Execution Command

The container executes the run command pointing to the configuration file: run /rospo.yaml