Managing Port Forwarding to your OpenShift Application

All communication with your application’s gears occurs over the Secure Shell (SSH) protocol. One of the features of SSH is port forwarding, which allows you to securely communicate with your gear and make it appear as if the services on the gear are running on your own machine.

The basic idea is that SSH takes ports on your local machines and tunnels them over a secure connection to a port on the remote machine. For example, you can use SSH to take port 9999 on your local machine and have it attach to port 9999 on your gear, which is the port that JBoss EAP Web Console listens on. Now when you connect to port 9999 on your local machine, all your traffic to that port will be sent directly to port 9999 on your gear.

You need this capability when you want to connect to anything not running on the OpenShift public ports: 22, 80, 443, 8000, and 8443.

Some potential uses of SSH port fowarding are:

  • Attaching your database admin software on your local machine to the DB in your OpenShift application

  • Desktop software such as Excel or QGIS directly using data on the server

  • Having your code on your local machine work with the database in your OpenShift application

  • Attaching the debugger on your local machine to the process running on OpenShift

  • Open the administrative web console for an application server running on a non-open port, such as JBoss EAP running on port 9990.

Basic Usage

If you already know how to set up port-forwarding with the SSH command line tools, then you can use those same commands with OpenShift.

The RHC command line tools and the JBoss Tools integration both give you an easy way to port-forward internal ports from your application’s gears. For the RHC tool, enabling port forward only requires:

$ rhc port-forward -a <app_name>

or in Eclipse:

Port forwarding in Eclipse for an application named _parkmaps_

A Working Example

Here is an example of using the command line tools and port forwarding to connect to a PostgreSQL database from your local machine.

Run rhc port-forward command to have the command-line tools port forward all listening ports over SSH:

$ rhc port-forward -a exampleapp
Forwarding ports ...

To connect to a service running on OpenShift, use the Local address

Service    Local               OpenShift
---------- -------------- ---- ----------------
httpd  =>
postgresql  =>

Press CTRL-C to terminate port forwarding

You can see the command has now mapped port 5432 in the application to port 5432 on the local machine. You can now connect to the local loopback address ( on port 5433 to connect to PostgreSQL running on the gear.

$ psql -h -p 5433 -U adminm4rvN42 exampleapp
Password for user adminm4rvN42:
psql (9.3.2, server 9.2.4)
Type "help" for help.

exampleapp=# <emphasis role="strong">\dt</emphasis>
                List of relations
 Schema |      Name       | Type  |    Owner
 public | long_adjective  | table | adminm4rvN42
 public | noun            | table | adminm4rvN42
 public | short_adjective | table | adminm4rvN42
(3 rows)


You could use this same pattern to connect to any other service running in your application on a non-publically exposed port.