Skip to content

SSH port forwarding - explanation & use cases

What is ssh port forwarding?

SSH port forwarding, which sometimes also is called an SSH tunnel is a technique to map a remote port on a remote device to your local machine. A general problem for industrial IoT applications is that some parameters need to be configured or they contain interesting information but the device they are running on is shielded from external access through firewalls. Often that makes sense as they operate an open web server on port 80 (http) or they have a low security web application setup with only basic login and authentication or none at all. Therefore these devices are isolated from the outside. But there is a technique called ssh port forwarding that in conjunction with the remote access solution will allow to create a secure tunnel to a port or service to the other devices as well.

With the tools provided in the system such as qbee-connect and qbee-cli it is possible to:

  • map any port of the remote device securely to a localhost port on a local machine
  • forward any port of any other device in the remote network that can be reached by the device running the agent to a localhost port on a local machine

Typical services used with port forwarding

VNC for remote desktop sharing

VNC is a remote desktop protocol. It is the abbreviation for Virtual Network Computing. It is a cross-platform screen sharing system that was created to remotely control another computer. This means that a computer’s screen, keyboard, and mouse can be used from a distance by a remote user from a secondary device as though they were sitting right in front of it. The standard port used for VNC is 5900, although this can vary. Mapping that specific port from a remote device allows you to remotely control that machine.

RDP or remote desktop protocol

RDP is a proprietary and Microsoft specific remote desktop protocol that allows you to remote control computers. While it is mainly used in Windows context there are clients available for Linux, Unix, macOS and others. By default, the server listens on TCP port 3389 or on the UDP port 3389.

HTTP and HTTPS

Any http port (usually 80) or https port (usually 443) can be forwarded. This is used to access HVAC systems, control systems or any other system that provides a standard user interface. A typical example could be a router or firewall.

Modbus

Modbus over TCP is a very popular protocol in industrial applications. The standard port for the TCP traffic is 502. This port can also be bridged to a localhost port on your local computer. While developing applications we observe often customers that map their Modbus box UI user interface to check that traffic is really ongoing. In addition they can feed the traffic directly in consuming applications for quick testing and prototyping.

MQTT

MQTT is often forwarded to cloud systems. In the early phase of an IoT development project this might only be available on a localhost port on the edge device. Just use the MQTT port (often default as 1883) and port forward it to your local machine to quickly get access to the data.

Useful tools that can run over ssh port forwarding

Typical tools that run on top of ssh are scp, sftp, rsync, sshfs and many others as well. The qbee-connect tool allows you to connect securely to port 22 and offers a mapped port in the UI. This mapped port can then be used to work with the tools above. Please see the following examples:

  • remote two-way file access through scp as described in here
  • remote two-way file and folder synchronization with rsync as described here

But there are also a lot of very interesting graphical tools available that handle one or many of these services above. For your convenience we list some here, but they are by no means complete:

Use localhost or 127.0.0.1 as server url, the correct mapped port and your standard credentials.

Two-way file copy with scp

Task - download remote syslog file

  1. open qbee-connect on your machine and connect to the remote device with ssh on port 22 qbee-connect-prepare-scp
  2. qbee-connect maps port 22 on a different localhost port. In this case it is 62530
  3. run a scp command from your local machine to the remote device using the -P command to use the mapped port 
    scp -P 62530 root@localhost:/var/log/syslog syslog_ctr-700
  4. this copies the remote syslog file to the local device qbee-terminal-scp
  5. task completed. This works also across firewalls or NATs.

If you are on Windows and want a graphical UI you can also look at the free tool WinSCP. This allows to do the whole process graphically.

Please configure it like this. The port is the port mapped by qbee-connect.

!qbee-connect-winscp

Then you will have full access to the remote file system:

!qbee-connect-winscp-full

This video shows an example how this was done with Cyberduck on a MAC.

Two-way file copy with rsync

If you want to sync a remote directory structure or file from or to your remote edge devices this can be easily achieved with rsync. This works on Linux, Windows and Mac utilizing the secure built-in qbee VPN through the qbee-connect tool.

Use qbee-connect or qbee-cli to establish a connection and connect.

ssh -p 12345 username@localhost

Through rsync you can now transfer files and directories from and to the device.

Some common rsync command options

  • -v : verbose
  • -r : copies data recursively (without preserving timestamps and permission while transferring data)
  • -a : archive mode, archive mode allows copying files recursively and it also preserves symbolic links, file permissions, user & group ownerships as well as timestamps
  • -z : compress file data
  • -h : human-readable, output numbers in a human-readable format
  • -e : which protocol name to use (e.g. ssh)

We define the following:

  • qbee mapped port : $PORTNUMBER, the mapped port from qbee-connect (here: 12345)
  • user on remote device : $USER (here: username)
  • path of the source directory in the remote device : $REMOTE_SOURCE_DIRECTORY
  • path of the local destination directory : $LOCAL_DESTINATION_DIRECTORY

Linux version

Make sure you have rsync installed, otherwise install it via your package manager (e.g. in Ubuntu use sudo apt-get install rsync). Got to your terminal and use 

rsync -avz -e "ssh -p $PORTNUMBER" $USER@localhost:$REMOTE_SOURCE_DIRECTORY $LOCAL_DESTINATION_DIRECTORY

Now you should be able to see all copied files in your local $LOCAL_DESTINATION_DIRECTORY. All directories, files and subdirectories are transferred.

Mac version

All versions of macOS have rsync build into it as a standard tool. Please see under Linux for the syntax to call it from the terminal window.

This is how a typical rsync command would look:

rsync -avz -e "ssh -p 53467" pi@localhost:/home/pi /Users/IoT/device/RPI1

There are UI based tools available as well (one example is Acrosync, please see under Windows)

Windows version

Windows does not have a built-in version of rsync available. You can either find an open source package, use Cygwin, use WSL (Windows subsystem for Linux) or you can use a UI based commercial tool like Acrosync.