25 Oct 2016, 10:28 Containers Secure Gateway Connectivity Docker

Using the Secure Gateway to Connect from Your Local Network to the Cloud

The IBM Bluemix Secure Gateway service allows connectivity from Bluemix applications to local/on-premise destinations. There are many excellent articles which cover this scenario, such as:

However, a lesser-known scenario is that it can also connect back from your on-premise system to cloud-based destinations. Although this may not be the primary motivation for using it in many scenarios, it can be very useful with restrictive on-premise networks which don’t allow outbound connectivity.

This blog post walks through a very simple example of setting up this connectivity to connect to a public JSON-based service (http://loripsum.net/api). Although on your local test system, it is most likely that direct connectivity to that endpoint is possible, in many on-premise enterprise scenarios, that may not be so straightforward. This Secure Gateway setup thus becomes one possible option. We will define a Secure Gateway service, and use the Docker-based client, running locally on your machine, to connect back to the Secure Gateway.


Instructions for this tutorial are written assuming you are using OS X, although they can probably be adapted to other platforms fairly easily.

Define the Secure Gateway

  • In a browser in which you are logged in to Bluemix, navigate to the URL https://console.ng.bluemix.net/catalog/services/secure-gateway/. Click on “Create” to create the Secure Gateway service. Note: if you already have an instance of the Secure Gateway service in the space in which you are working, you will be unable to create a new one. You can use the existing instance of the service you have and simply create a new Gateway within it (navigate to the Secure Gateway Dashboard in the Bluemix interface). Note also that the Secure Gateway has a cost attached once you exceed a certain threshold of data. Please make sure you are comfortable with this restriction.

  • You will now be in the Secure Gateway Dashboard. At this point, click “Add Gateway”. Specify a name for the Gateway (e.g. “GatewayFromLocal”). For this simple tutorial, you can disable “Require security token to connect clients” and “Token Expiration”. Click “Add Gateway”. It will look like this:

    Add Gateway

  • Once you’ve created your Gateway, you’ll need to add the Client (the local Docker container which connects back from your machine to Bluemix). Locate the Gateway on the administration console (it will have a red X to show it is not yet connected). It will look like this:

    Gateway Disconnected

Click on it.

  • Click on “Add Clients”. This will bring up a dialog with multiple connectivity options. Click on “Docker”. This will show the precise Docker command required to run the local Gateway client on your local machine. The dialog should look like this:

    New Gateway

The identifier at the end of docker run command is the ID of this individual gateway.

  • You will need to modify the docker command to make sure that the port number we pick later on (called the “Client Port”) is mapped from the Docker container (which has a separate network, with a separate set of ports) to your host machine. Add a parameter like -p 6655:6655 to your command (you can pick any number you want, although it’s recommended to be above 1024). It should look like this:

    docker run -p 6655:6655 -it ibmcom/secure-gateway-client vJOMUBbT9Ax_prod_ng

Run the docker run command locally on your machine. You should see output that looks a bit like this (your client ID will, of course, be different from the one shown).

    IBM Bluemix Secure Gateway Client Version 1.6.0
    You  are running the  IBM Secure  Gateway Client for Bluemix. When you enter the provided docker
    command the IBM Secure Gateway Client  for Bluemix automatically downloads as a Docker image and
    is executed on your system/device. This is released under an IBM license. The  license agreement
    for IBM  Secure Gateway Client for Bluemix is available at the following location:


    Your use of the components of the package and  dependencies constitutes your acceptance  of this
    license agreement. If you do  not want to accept the license, immediately quit  the container by
    closing the  terminal  window or by  entering 'quit' followed by the ENTER key. Then, delete any
    pulled Docker image from your device.

    For client documentation, please view the ReadMe located at:
    .rpm and .deb installers: /opt/ibm/securegateway/docs/
    .dmg installer:           <installation location>/ibm/securegateway/docs/
    .exe installer:           <installation location>\Secure Gateway Client\ibm\securegateway\docs\

    <press enter for the command line>
    [2016-10-25 04:57:37.944] [INFO] (Client ID 1) No password provided. The UI will not require a password for access
    [2016-10-25 04:57:37.953] [WARN] (Client ID 1) UI Server started. The UI is not currently password protected
    [2016-10-25 04:57:37.953] [INFO] (Client ID 1) Visit localhost:9003/dashboard to view the UI.
    [2016-10-25 04:57:38.169] [INFO] (Client ID 11) Setting log level to INFO
    [2016-10-25 04:57:39.249] [INFO] (Client ID 11) The Secure Gateway tunnel is connected
    [2016-10-25 04:57:39.546] [INFO] (Client ID Hh2eUmsFUi2_u7U) Your Client ID is Hh2eUmsFUi2_u7U
  • Because you specified the -it flag to docker, the docker client will continue to run. Leave the window open so you can monitor the client easily. Very shortly afterward, the red cross against the Gateway in the Secure Gateway Dashboard should turn to green to show that the Docker client has successfully made a connection. If it does not, proceed no further and debug.

  • Now, we’ll add a “Destination” for a Cloud-based service which we can invoke locally. From within the Gateway control panel, click on “Add destination”:

    Add Destination

  • Click “Advanced Setup” and fill out the screen as shown. The “Client Port” is the port locally within the Docker container - choose the same number you chose earlier for the docker run command. Click on ‘Add Destination’:

    Add Destination Details

(Occasionally I have found that the process of adding a destination can hang at this point. If this happens, refresh the page - you will probably see that the destination has not been added to the gateway. Then, add the destination again, using the same details, but select “TCP” as the type. Once it is created, go in and edit the details, changing the type to “HTTP”. This should work).

  • If the destination is successfully created, you should see a message that looks like this:

    [2016-10-25 05:19:55.346] [INFO] (Client ID Hh2eUmsFUi2_u7U) Creating TCP server for reverse connections. Listening on port 6655
  • You can now test this. Open a browser to the URL http://loripsum.net/api. You should see some pseudo-HTML containing some Lorem Ipsum text. Your network may allow this directly, depending on your proxy settings, but of course this scenario is most useful when this direct connectivity is not possible!

  • Now, open a browser to http://localhost:6655/api. You should see exactly the same result. This means that your browser is connecting through your local Docker client, across the Secure Gateway, and out onto the public internet endpoint. Even though in this case your network may allow direct connectivity to the original endpoint, this illustrates the values of the Secure Gateway in “bridging” connectivity.


Any questions or comments, contact me at andrew DOT ferrier AT uk DOT ibm DOT com.