Fabric 2+ SSH Connections Through a SOCKS Proxy

Fabric's remote commands travel over SSH. To carry that SSH connection through a SOCKS server, give Fabric a connector that speaks SOCKS and returns the destination's byte stream.

The Connection API introduced in Fabric 2 accepts a command string as its gateway. Fabric uses that string as a ProxyCommand. With an existing OpenBSD-compatible nc that supports its proxy options, the configuration can be:

from fabric import Connection

connection = Connection(
    "app.example.net",
    user="deploy",
    gateway="nc -X 5 -x proxy.example.net:1080 %h %p",
)

This example uses the normal SSH port, 22. The connector's -X 5 selects SOCKS5, while -x identifies the proxy endpoint. The host and port placeholders supply the SSH destination. For a public SSH destination, an unauthenticated endpoint from the SOCKS5 proxy list can fill the proxy address if it permits that destination and port. Configure the command using the options of the actual connector installed on the machine; programs named nc do not all expose the same interface.

The connector runs locally, where Fabric runs. The application server does not need that helper merely because it is the SSH destination. Once the stream is established, Fabric still performs SSH negotiation and authenticates the deploy account on app.example.net. Any authentication required by the SOCKS server belongs to the connector and must be supported by it.

Fabric can also read a ProxyCommand from SSH configuration. That can be convenient when the same route is used by several SSH tools. Use one intended gateway definition for the connection, rather than combining a command-style gateway with a separate jump-host gateway for the same destination.

When the intermediary is an SSH server

A Fabric Connection object supplied as gateway means something different: Fabric connects to that SSH gateway and requests a channel to the final host. Use that form for an SSH jump host. A SOCKS listener is not an SSH server, so it needs the command-style connector above.

This transport choice also has a clear limit. It routes Fabric's SSH connection. A command executed on the remote host that later downloads a repository or package makes a new outbound connection from that host, under that program's own proxy configuration.