Skip to content

Local Port Forwarding

Use local port forwarding to forward data securely from an application client running on the same computer as the Secure Shell client. When you configure local port forwarding, you designate an arbitrary local port to use for forwarding data, and a destination host and port to receive the data. Local port forwarding works as follows.

  1. When the Secure Shell connection is established, the Secure Shell client opens a listening socket on the local computer (the Secure Shell client host) using the designated local port. In most cases, this socket is available only to applications running on the Secure Shell client host.

    The gateway ports setting controls whether locally forwarded ports are available to remote applications. By default this setting is not enabled, and the client uses the loopback address ("localhost" or 127.0.0.1) when it opens a socket for local port forwarding. This prevents applications running on other computers from connecting to the forwarded port. When you enable gateway ports, a remote application client can open a socket using the Secure Shell client's Ethernet address (such as an IP address, a URL, or a DNS name). For example, a Secure Shell client running on acme.com might be configured to forward port 8088. When gateway ports are not enabled, the forwarded socket is localhost:8088. When gateway ports are enabled, the forwarded socket is acme.com:8088.

    Caution

    Enabling gateway ports reduces the security of your client host, network, and connection because it allows remote applications to use the forwarded port on your system without authenticating.

  2. An application client is configured to connect to the forwarded port (rather than directly to the application server host and port). When that client establishes a connection, all data is sent to the listening port, and then redirected to the Secure Shell client.

  3. The Secure Shell client encrypts the data and sends it securely through the Secure Shell channel to the Secure Shell server.

  4. The Secure Shell server receives the data, decrypts it, and redirects it to the destination host and port used by the application server.

    Note

    If the final destination host and port are not on the Secure Shell server host, data is sent in the clear between the Secure Shell host and the application server host.

  5. The return data from the application server is directed to the Secure Shell server, which encrypts it and sends it securely to the Secure Shell client through the SSH tunnel. The Secure Shell client decrypts the data and redirects it to the original application client.

The general command-line syntax for local port forwarding is:

ssh -L listening_port:app_host:hostport user@sshserver

The diagrams that follow illustrate two ways to use this.

In the configuration shown above, the application client and the Secure Shell client both run on HostA. The Secure Shell server and application server both run on HostB. All data sent to port 2222 on HostA is forwarded to port 222 on HostB. In this arrangement, all data in transit is securely encrypted. The following command (in which localhost identifies the loopback address on HostB) configures this:

ssh -L 2222:localhost:222 user@HostB

The following diagram illustrates local port forwarding to a third host. In this configuration, the application server runs on a different host than the Secure Shell server. All data sent to port 2222 on HostA is forwarded to port 222 on HostC.

The following command configures this:

ssh -L 2222:HostC:222 user@HostB

Note

Data sent between HostB and HostC is not encrypted.

More information