Working over SSH on a big beefy remote machine is a great way to extend the
life of any laptop, but presents challenges when developing network-based
services. Fortunately OpenSSH has a “port forwarding” feature which has been around for a number of
years. Port forwarding allows the user to tunnel a port from the remote machine back to
their local machine, in essence allowing you to access a remote service bound to port 8000 on your own localhost:8000
. When I first learned about this, I would fiddle around
with my ssh
invocations or hardcode a list of potential ports forwarded in
my ~/.ssh/config
. If I was working on a new service that needed a port not yet forwarded, I would disconnect, add it to the list of ports in my config
file, and then reconnect. That was until my pal nibz
(nibalizer) showed me how to dynamically add
port forwards to an already existing session.
OpenSSH provides a number of escape characters
that can be used on a running connection, one of these is ~C
which will open
up a little command line interface:
❯
ssh> ?
Commands:
-L[bind_address:]port:host:hostport Request local forward
-R[bind_address:]port:host:hostport Request remote forward
-D[bind_address:]port Request dynamic forward
-KL[bind_address:]port Cancel local forward
-KR[bind_address:]port Cancel remote forward
-KD[bind_address:]port Cancel dynamic forward
From this simple command line you can add or remove local, remote, and dynamic
port forwards! Pretty snazzy! When I was first learning how to use these escape
characters I had a difficult time getting the key-combination correct,
frequently I would somehow screw it up and just send ~C
to the shell:
❯ ~C
zsh: no such user or named directory:
The approach that I have found most reliable is to hold my left shift key down
while I hit ~
and C
in sequence. In essence, my left pinky finger keeps
shift depressed while my middle finger and then my pointer finger consecutively
hit the two keys. I share this because when I first started to use these escape
sequences I could never get the timing/cadence correct the first time and it
felt like I was wasting more time than it would take to just disconnect and
reconnect.
Another tip is to make sure you have detached from any active tmux
sessions, as tmux
has it’s own escape sequences and key bindings that you likely want to avoid triggering.
Once you get the hang of it, you can dynamically allocate new ports for whatever service you’re developing and then easily use your local browser/client to access the service under development. Much better!
For more escape characters, refer to the ssh(1)
manpage via man ssh
which has a section dedicated to these magic key combos.
ESCAPE CHARACTERS
When a pseudo-terminal has been requested, ssh supports a number of functions through the use of an escape character.
A single tilde character can be sent as ~~ or by following the tilde by a character other than those described below. The escape
character must always follow a newline to be interpreted as special. The escape character can be changed in configuration files us-
ing the EscapeChar configuration directive or on the command line by the -e option.
The supported escapes (assuming the default ‘~’) are:
~. Disconnect.
~^Z Background ssh.
~# List forwarded connections.
~& Background ssh at logout when waiting for forwarded connection / X11 sessions to terminate.
~? Display a list of escape characters.
~B Send a BREAK to the remote system (only useful if the peer supports it).
~C Open command line. Currently this allows the addition of port forwardings using the -L, -R and -D options (see above). It
also allows the cancellation of existing port-forwardings with -KL[bind_address:]port for local, -KR[bind_address:]port for
remote and -KD[bind_address:]port for dynamic port-forwardings. !command allows the user to execute a local command if the
PermitLocalCommand option is enabled in ssh_config(5). Basic help is available, using the -h option.
~R Request rekeying of the connection (only useful if the peer supports it).
~V Decrease the verbosity (LogLevel) when errors are being written to stderr.
~v Increase the verbosity (LogLevel) when errors are being written to stderr.