+

Search Tips   |   Advanced Search

Enable HTTP tunneling

HTTP tunneling enables clients, that reside outside of a firewall, to bundle all of the information, that 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.

Make sure the client-side ORB is an IBM ORB. Tunneling does not work if you are using a non-IBM ORB on the client.

Also, if Secure Sockets Layer (SSL) security is required for the tunneling, verify 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, you 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, 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_6.1.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 the tunneling clients if your security procedures require that all communication to the servers is SSL secured.

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

    Before we can run the IIOPTunnelServlet servlet on the server, you must make it part of an application that we can install on the server. We can use an application assembly tool to create an installable IIOPTunnel.ear file that includes this servlet. For example, if you use the assembly tool that is 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_7.0.0.jar file to the Web Project Build Path.

      Before we can register the new servlet in the Web Deployment Descriptor, add the IIOPTunnelServlet servlet, that resides in the WAS_HOME/lib/plugins/com.ibm.ws.runtime_7.0.0.jar file, to the 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_7.0.0.jar file, and then click OK.

  2. Export the EAR file.

    1. Right click on the IIOPTunnelEAR project.

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

    3. Click Finish.

      You get the 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:port/context_root/Servlet_URLmapping

    Thehost:port are the host name and port assigned to teh server on which the IIOPTunnelServlet resides. The port can be either an HTTP or an HTTPS port, depending on the 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, we 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 you 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: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 specified 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.

    We 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: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 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.