Port forwarding

Port forwarding sends network connections through an SSH session – for example to reach a database that only listens on the server, or to browse through the server as a proxy. In kaiport, forwarding rules belong to an SSH connection: they start when the session connects and stop when it ends. This page explains the three kinds of forwarding, how to set them up and how they combine with jump hosts.

Kinds of forwarding

Forwarding is only available for SSH connections, not for storage connections.

Add a forwarding rule

1. Open the connection with Edit and switch to the Advanced tab.
2. Under Port forwards, click Forward. A new rule appears: Local (-L) from 127.0.0.1:8080 to localhost:80, already active.
3. Choose the kind: Local (-L), Remote (-R) or SOCKS5 (-D).
4. Enter the listen host and port.
5. For local and remote forwarding, enter the destination host and port after the arrow.
6. Click Save.

Port forwards on the Advanced tab

An empty listen host counts as 127.0.0.1, which keeps the port reachable only from the same machine.

Several rules

A connection can have as many rules as you need. Each rule has its own Active switch, so you can turn a tunnel off without deleting it; the trash icon deletes it. The card in the start window shows the number of rules, for example 3 tunnels – active or not.

When tunnels run

• kaiport starts the active rules as soon as the session is connected, after the login.
• The tunnels stop when the session ends: when you close the tab or pane, or when the connection drops. A reconnect starts them again.
• Changes to the rules apply the next time you connect. A running session keeps the rules it started with.
• Tunnels belong to one session. If you open the same connection twice, the second session can't listen on the ports the first one already uses.

Check a tunnel

kaiport doesn't show a status for each tunnel. If a rule can't start, the session still connects normally and only that tunnel is missing. To check a local tunnel or the proxy, point a program at the listen port – if nothing answers there, the rule didn't start. Common reasons:

• The listen port is already in use on your computer, for example by a local database or another session with the same rule.
• The server doesn't allow forwarding (AllowTcpForwarding in its sshd_config). A local tunnel then accepts connections on your computer but closes them right away.
• For remote forwarding, the server refuses the port: ports below 1024 need a login as root.
• For remote forwarding on 0.0.0.0, the server binds to 127.0.0.1 anyway unless its sshd_config sets GatewayPorts clientspecified or GatewayPorts yes.
• The destination doesn't accept the connection, for example because the service isn't running or the destination host is wrong.

Examples

Reach a database on the server

PostgreSQL runs on the server and only listens on 127.0.0.1:5432. Add a rule:

Connect, then point your database client at port 5433 on your computer:

psql -h 127.0.0.1 -p 5433 -U app appdb

Using 5433 on your side avoids a clash with a PostgreSQL running on your own computer.

Open an internal web interface

An admin interface runs on 10.0.0.12:8080 in the server's private network. Add a Local (-L) rule from 127.0.0.1 port 8080 to 10.0.0.12 port 8080, connect, and open http://localhost:8080 in your browser.

Use the server as a SOCKS proxy

Add a SOCKS5 (-D) rule on 127.0.0.1 port 1080. After connecting, set SOCKS5 proxy 127.0.0.1, port 1080 in your browser or system network settings. Websites then see the server's address, and you reach hosts in the server's network.

The proxy handles TCP connections (CONNECT) without a password. When a program sends host names to the proxy, the server resolves them.

Show a local development server to the server

Your web app runs on your computer at localhost:3000, and a service on the server should call it. Add a rule:

On the server, curl http://127.0.0.1:8080 now reaches your development server.

Tunnels and jump hosts

With a jump host, the SSH session runs through the jump host to the target, and the tunnels start on the target server. Destination hosts are therefore seen from the target: localhost in a local rule is the target server, not the jump host.

Example: the database server db-01 is only reachable through bastion. Give the connection db-01 the jump host bastion and the rule Local (-L) from 127.0.0.1:5433 to localhost:5432. After connecting, your database client reaches the database on db-01 at port 5433 on your computer.

Tunnels on other computers

The forwarding rules are part of the connection and of its export. When you import the connection on another computer, its tunnels start there when you connect – check that the listen ports are free on each computer.