Enable HTTP tunneling


 

+

Search Tips   |   Advanced Search

 

HTTP tunneling enables clients, residing outside of a firewall, to bundle all of the information, that the client-side 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 that the client-side ORB is an IBM ORB. Tunneling does not work if we are using a non-IBM ORB on the client.

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, residing 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 WAS 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 residings inside of a firewall. This class file, along with the following three class files, are bundled within...

WAS_HOME/plugins/com.ibm.ws.runtime_6.1.0.jar

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 the 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, 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 that is shipped with WAS ND:

    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, residings 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. Go to...

      Export | EAR File

      ...browse to the 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 the IIOPTunnel.ear file, which is ready for you to deploy.

  3. Install the IIOPTunnel.ear file on the target appserver.

    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 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:9082/IIOPTunnel/IIOPTunnelServlet

    To verify that the servlet is deployed and running successfully, we can open a browser and point to...

    http:// hostname:9082/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:9082/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:9082/IIOPTunnel/IIOPTunnelServlet?debug=true

  5. Set 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:9082/IIOPTunnel/IIOPTunnelServlet
    com.ibm.CORBA.FragmentSize=0

    To enabled tunneling on the client ORB, the property...

    com.ibm.CORBA.ForceTunnel

    ...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 9082 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:9082/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 admin console, click...

      Servers | Server Types | WebSphere application servers

      ...click the server where the tunneling servlet is installed.

    2. Go to...

      ORB Service | Custom properties | New

      Specify com.ibm.CORBA.FragmentSize in the Name field and 0 in the Value field.

    3. Click OK, and then save the changes.

  7. Stop and then restart the appserver.

 

Next steps

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

 

Related tasks

Manage Object Request Brokers