Skip to content

feat: Support for Jump Hosts (ProxyJump) and Proxy Commands #82

@JacobCallahan

Description

@JacobCallahan

Summary

Add native support for connecting through bastion/jump hosts and proxy commands in both Connection and AsyncConnection, so users can reach servers in protected subnets without manual SSH tunneling.

Motivation

Many production environments place target hosts behind a bastion (jump) host or require a local proxy command as the transport layer. Currently, users must set up external tunnels before using hussh, which adds friction and defeats the purpose of a high-level SSH library.

Proposed API

ProxyJump

# Connect to target via a bastion host
conn = Connection(
    "target.internal",
    username="user",
    proxy_jump=Connection("bastion.example.com", username="user", password="..."),
)

# Async variant
conn = await AsyncConnection(
    "target.internal",
    username="user",
    proxy_jump=AsyncConnection("bastion.example.com", username="user", password="..."),
)

ProxyCommand

conn = Connection(
    "target.internal",
    username="user",
    proxy_command="nc %h %p",
)

Implementation Notes

  • ProxyJump: Establish an authenticated session to the bastion, then open a direct-tcpip channel to the target host and use it as the transport for a second SSH handshake. Maps cleanly onto ssh2-rs's channel API.
  • ProxyCommand: Spawn the local command as a subprocess and wire its stdin/stdout as a raw I/O stream into the ssh2/russh session constructor.
  • Both variants should support the full existing auth options (password, key, agent) on the inner connection.
  • Consider accepting a plain (host, port) tuple or string shorthand (user@host:port) for proxy_jump as a convenience.

Acceptance Criteria

  • proxy_jump parameter supported on Connection and AsyncConnection
  • proxy_command parameter supported on Connection and AsyncConnection
  • Integration tests using the existing Docker test infrastructure (add a second container as a bastion)
  • Documentation and usage examples updated

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions