+

Search Tips   |   Advanced Search

Enable HTTP tunneling

HTTP tunneling enables clients residing outside of a firewall to bundle information the client-side Object Request Broker (ORB) needs to send to the server-side ORB, into a normal HTTP request. This request can then be sent to the server on port 80, just like any other HTTP request.

Verify the client-side ORB is an IBM ORB. Tunneling does not work if we are using a non-IBM ORB on the client.

Also, if SSL security is required for the tunneling, make sure that the required certificates and key files are configured.

Sometimes clients residing outside of a firewall need to communicate with modules, such as EJB modules, that reside on a server inside of the firewall. The client-side and server-side ORBs manage this interaction between the client and the server. However, firewalls normally block the ports that a client, uses to talk to the server-side ORB. Therefore if the installation uses a firewall that blocks the ports a client uses to talk to the server-side ORB, we should set up HTTP tunneling.

The IIOPTunnelServlet, which is shipped with the product as class file com.ibm.CORBA.services.IIOPTunnelServlet.class, allows an HTTP client, such as a Java client, that is embedded with RMI-IIOP, to communicate with a server that resides inside of a firewall. This class file, along with the following three class files, are bundled within the WAS_HOME/plugins/com.ibm.ws.runtime_9.0.jar file. These additional class files enhance the servlet's capabilities.

When tunneling is enabled, the IIOPTunnelServlet servlet on the server receives the HTTP request and unpacks all of the ORB information. The servlet then calls the server-side ORB on the client's behalf. The server-side ORB treats the request as it would treat any normal ORB request and responds to the servlet. The servlet packs the ORB response into an HTTP response and sends the response back to the client-side ORB, through the firewall. The client-side ORB unpacks the HTTP response and pulls out the response.

Tunneling can operate over HTTPS as well as over HTTP. Therefore, we can use SSL security to secure your tunneling clients if our security procedures require that all communication to your servers is SSL secured.


Tasks

  1. Create an installable IIOPTunnel.ear file that includes the IIOPTunnelServlet servlet.

    Before we can run the IIOPTunnelServlet servlet on the server, make it part of an application that we can install on the server. Use an application assembly tool to create an installable IIOPTunnel.ear file that includes this servlet. For example, if we use the assembly tool shipped with the product:

    1. Start the tool.

    2. Open the WEB perspective.

    3. In the Project Explorer view, right-click in an empty pane and select New > Dynamic Web Project.

    4. In the Create Dynamic Web Project wizard, change the project Name to IIOPTunnel, or another name that is meaningful to you. By default, the Add Module to an EAR project option is selected, the EAR project name is set to IIOPTunnelEAR, and the Context Root is set to IIOPTunnel.

    5. Keep these default settings and click Finish.

    6. Add the com.ibm.ws.runtime_9.0.jar file to the Web Project Build Path.

      Before we can register the new servlet in the Web Deployment Descriptor, we must add the IIOPTunnelServlet servlet, that resides in the WAS_HOME/lib/plugins/com.ibm.ws.runtime_9.0.jar file, to your build path.

      1. Right-click the IIOPTunnel Web Project, and select Properties > Java Build Path.
      2. Select the Libraries tab and press the Add external JARs button.
      3. Add the com.ibm.ws.runtime_9.0.jar file> OK.

  2. Export your EAR file.

    1. Right click on the IIOPTunnelEAR project.

    2. Click Export > EAR File, browse to your selected destination directory and specify the EAR file name as IIOPTunnel.ear, or the file name specified in Step 1d.

    3. Click Finish.

      You get your IIOPTunnel.ear file, which is ready for you to deploy.

  3. Install the IIOPTunnel.ear file on the target application server. We can accept all default values during installation.

    Remember to adjust the tunnelAgentURL in the client to reflect the actual location of the IIOPTunnelServlet on the server.

    Detailed explanation of the tunnel URL format: 

    http(s)://host_name:port/context_root/Servlet_URLmapping

    Thehost_name:port are the host name and port that is assigned to teh server on which the IIOPTunnelServlet resides. The port can be either an HTTP or an HTTPS port, depending on our security requirements.

    The context_root and Servlet_URLmapping values must match the values defined for the context-root and servlet-URLmapping elements in the servlet web.xml file.

    For example, if the servlet is installed on the default server, and context-root=iioptunnel, and Servlet-URLmapping=tunnel, the following URL must be specified for tunnelAgentURL in the client: 

    http://localhost:9080/IIOPTunnel/IIOPTunnelServlet

    To verify that the servlet is deployed and running successfully, you can open a browser and point to http:// hostname:9080/iioptunnel/tunnel. If the servlet is working, the browser tries to download the servlet as if it were just a normal file. We can then cancel the download.

  4. Verify that the servlet is deployed and running successfully

    To verify that the servlet is deployed and running successfully, we can open a browser and point to http:// hostname:9080/IIOPTunnel/IIOPTunnelServlet. If the servlet is working, the browser tries o download the servlet as if it were just a normal file. Simply cancel the download.

    Specify the following parameters if we encounter a problem deploying and running the servlet. 

    -Dcom.ibm.CORBA.TunnelAgentURL=https://localhost:9080/IIOPTunnel/IIOPTunnelServlet?debug=true

  5. Configure the ORB Service for the client-side ORB to enable tunneling

    The client determines whether standard IIOP and HTTP tunneling should be used for communication with the server-side ORB. Therefore set the following ORB properties on the client. 

    com.ibm.CORBA.ForceTunnel=ALWAYS
com.ibm.CORBA.TunnelAgentURL=http://host_name:9080/IIOPTunnel/IIOPTunnelServlet com.ibm.CORBA.FragmentSize=0

    To enabled tunneling on the client ORB, the com.ibm.CORBA.ForceTunnel property must be set to ALWAYS. This setting indicates that this client is always going to tunnel. Other values that can be specified for the com.ibm.CORBA.ForceTunnel property are:

    • NEVER, which indicates to disable HTTP tunneling. If a TCP connection fails, a CORBA system exception (COMM_FAILURE) occurs.

    • WHENREQUIRED, which indicates to use HTTP tunneling if TCP connections fail.

    The second property specifies the fully qualified URL at which the tunneling servlet is reached. The port 9080 is the WC_defaulthost port for the server. The port number you specify must match the port number specified in the configuration file, serverindex.xml, for the server on which the IIOPTunnelServlet servlet resides.

    The third property turns off ORB fragmenting. Normally, the ORB breaks up communications into fragments, to improve performance, but tunneling will not work if the ORB is fragmenting.

    You can also set these properties by adding them as parameters to the JVM command line: 

    -Dcom.ibm.CORBA.ForceTunnel=always 
-Dcom.ibm.CORBA.TunnelAgentURL=http://host_name:9080/iioptunnel/tunnel 
-Dcom.ibm.CORBA.FragmentSize=0

    Optionally, we can also set the following property to specify client-side security settings: 

    -Dcom.ibm.CORBA.ConfigURL=file:PROFILE_ROOT/properties/sas.client.props

  6. Turn off fragmenting on the server-side ORB. The only property that configure for the server-side ORB to enable tunneling is the com.ibm.CORBA.FragmentSize property. This property must be set to 0 to turn off fragmenting.

    1. In the administrative console, click...

              Servers > Server Types > WebSphere application servers, and click the server where the tunneling servlet is installed.

    2. Click ORB Service, then click Custom properties.

    3. Click New and then specify com.ibm.CORBA.FragmentSize in the Name field and 0 in the Value field.

    4. Click OK, and then save the changes.

  7. Stop and then restart the application server.


What to do next

The client can start to sent requests through the firewall to the server configured for HTTP tunneling.