Port forwarding and tunnels

Tunnels are saved forwarding profiles per session. Each tunnel has its own SSH connection and an explicit lifecycle — started from the session’s context menu or a menu in the sidebar, stopped by you or at quit.

The three kinds

Kind	What it does	Spec
Local	Connects a local port to a target reachable from the server — the classic ssh -L.	localPort:host:remotePort
Dynamic (SOCKS5)	Serves a SOCKS5 proxy on a local port that tunnels through the SSH server — the classic ssh -D.	a local port
Remote	Brings the server’s port to this Mac — the classic ssh -R.	remotePort:host:localPort

A forwarding needs an SSH session that logs in with its own login: a session that uses a login set or a jump host, or one that is not SSH, cannot carry one.

A forwarding no longer needs the server to offer SFTP, so it also works on an SSH server with SFTP turned off, such as a jump box.

A dynamic (SOCKS5) forwarding gives each client 30 seconds to say where it wants to go, and holds at most 64 such clients waiting at once; a client past either limit is disconnected. This keeps stalled clients from piling up.

Managing profiles

Create, edit, and remove profiles in the session’s context menu (or the tunnels sheet). Profiles are stored per session; deleting a session stops its forwardings.

If macSCP cannot read its list of forwardings (tunnels.json — damaged, or written by a newer version), a save or delete is refused with “The forwarding list could not be read, so it was not changed. Check …”, naming the file. The file is left as it is, and a running tunnel keeps running.

Starting and stopping

• Start a profile from the session’s context menu.
• A running tunnel reconnects with backoff when the underlying connection breaks.
• The state is visible in the sidebar; when a start cannot proceed, there is a row with the reason behind the alarm.
• Stop a tunnel from the same menu. Tunnels are stopped at quit, before the windows are torn down. Stopping a tunnel is never reported as a failure.

State and failures

A forwarding’s state and its failure cause are shown, in the app’s language, in four places:

• the State column of the tunnels sheet (Port forwarding),
• the State column of the Forwardings at launch sheet,
• the forwarding’s entry in the Dock menu (and the menu bar icon, when it is shown), as a tooltip,
• the forwarding symbol on the session’s sidebar row, as a tooltip.

When a forwarding fails, the state names the cause, for example:

You see	What it means
Port 8080 is already in use	Another program on this Mac already listens on the local port.
This Mac has no address …	The bind address of a local or dynamic forwarding is not one of this Mac’s addresses.
This Mac does not permit listening on port … at this address	macOS refused to let macSCP listen on that port and address.
The server refused to listen for the forwarding; an address other than loopback needs the server’s GatewayPorts setting	A remote forwarding asked for an address the server’s configuration does not allow.
A remote forwarding must name the server’s port; port 0 is not supported	A remote forwarding’s server port is 0.
The host key of … has changed	The server’s host key no longer matches — a hard stop; see Host keys.
Authentication failed / The key’s passphrase is wrong / No SSH agent answered	The login did not succeed.
Could not connect to the server	The SSH connection itself could not be made.

When the local port is refused for a reason this list does not name, the state shows the system’s own wording with its short name in parentheses — for example “Invalid argument (EINVAL)” — rather than an internal code, so the cause can be looked up and quoted in a bug report.

Failed connections while the tunnel is up

A forwarding stays up when a single connection through it fails — the target refuses it, for example. The state then reads Active · 2 connections failed, and the tooltip adds Last failure: with the cause of the most recent one. The count starts again at zero with the next connection that opens, and after every reconnect. A SOCKS5 client that gives up on its own, or connections lost because the SSH connection itself dropped, are not counted.

When a forwarding stops looking healthy

Once three connections in a row have failed, with none succeeding in between, the forwarding stops being shown as a healthy one:

• the mark on the session’s sidebar row turns orange and changes shape: a warning triangle instead of the forwarding arrows, with 3! beside it — the number of connections that failed in a row, with an exclamation mark on it,
• the Dock badge shows the same 3! instead of counting this forwarding among the working ones, so it cannot be read as “three forwardings are up”; with several forwardings failing at once it shows the longest run,
• the state reads Degraded · 3 connections failed in a row — in the tunnels sheet, in the Forwardings at launch sheet, and as the tooltip on the Dock menu entry and on the sidebar mark, with Last failure: below it as before.

A forwarding that has failed outright still shows a bare ! and the forwarding arrows, so the two are never told apart by colour alone. If one forwarding has failed while another keeps failing, the badge shows the failure: a forwarding that cannot be used at all comes first.

The very next connection that opens makes it green again — the same event that resets the count above, so a connection reaching the target is enough and nothing has to be transferred through it. Nothing is stopped, restarted or reconnected on your behalf: the forwarding is still up and still listening on its port — only what you are shown changes, so a forwarding nobody can use no longer looks like one that works.

Notification

When a forwarding fails while macSCP is in the background, macOS shows a Port forwarding failed notification with the forwarding’s name — see Notifications.

Automatic start

A profile can be brought up automatically at app start or at login (a login item). The state can be shown in the Dock as well.

From the command line

Tunnels can also be created, listed, edited, removed, and — in the foreground, the way ssh -L does — started from macscp-cli:

macscp-cli tunnels add prod-db --session prod --local 5432:127.0.0.1:5432
macscp-cli tunnels start prod-db --session prod

See Command line for the full reference, including the output of tunnels start.