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.
Before you begin
Make sure that 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, make sure that
the required certificates and key files are configured.
About this task
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 your 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, 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_6.1.0.jar file.
These additional class files enhance the servlet's capabilities.
- com.ibm.CORBA.services.redirector.ConnectionStream.class com.ibm.CORBA.services.redirector.Redirector.class
com.ibm.CORBA.services.redirector.RedirectorController.class
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, you can use Secure
Sockets Layer (SSL) security to secure your tunneling clients if your security
procedures require that all communication to your servers is SSL secured.
Procedure
- Create an installable IIOPTunnel.ear file that includes the IIOPTunnelServlet
servlet.
Before you can run the IIOPTunnelServlet servlet on
the server, you must make it part of an application that you can install on
the server. You 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:
- Start the tool.
- Open the WEB perspective.
- In the Project Explorer view, right click in an empty pane and
select New > Dynamic Web Project.
- 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.
- Keep these default settings and click Finish.
- Add the com.ibm.ws.runtime_6.1.0.jar file to
the Web Project Build Path.
Before you can register the new
servlet in the Web Deployment Descriptor, you must add the IIOPTunnelServlet
servlet, that resides in the WAS_HOME/lib/plugins/com.ibm.ws.runtime_6.1.0.jar file,
to your build path.
- Right click the IIOPTunnel Web Project, and select Properties > Java
Build Path.
- Select the Libraries tab and press the Add external JARs button.
- Add the com.ibm.ws.runtime_6.1.0.jar file, and then click OK.
- Export your EAR file.
- Right click on the IIOPTunnelEAR project.
- Click Export > EAR File, browse to your selected destination
directory and specify the EAR file name as IIOPTunnel.ear, or the file name
that you specified in Step 1d.
- Click Finish.
You get your IIOPTunnel.ear
file, which is ready for you to deploy.
- Install the IIOPTunnel.ear file on your target application server.
You can accept all default values during installation.
Remember to
adjust the tunnelAgentURL in the client to reflect the actual location of
the IIOPTunnelServlet on your 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 your
security requirements.
The context_root and Servlet_URLmapping values
must match the values that are 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. You can then cancel the download.
- Verify that the servlet is deployed and running successfully
To verify that the servlet is deployed and running successfully,
you 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
- 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 you must 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 that you want to disable HTTP tunneling.
If a TCP connection fails, a CORBA system exception (COMM_FAILURE) occurs.
- WHENREQUIRED, which indicates that you want 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 that
is 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, you can also set the
following property if you want to specify client-side security settings:
-Dcom.ibm.CORBA.ConfigURL=file:PROFILE_ROOT/properties/sas.client.props
- Turn off fragmenting on the server-side ORB. The only
property that you must 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.
- In the administrative console, click Servers -> Application
servers, and click the server where the tunneling servlet is installed.
- Click ORB Service, then click Custom Properties.
- Click New and then specify com.ibm.CORBA.FragmentSize in
the Name field and 0 in the Value field.
- Click Ok, then save the changes.
- Stop and then restart the application server.
What to do next
The client can start to sent requests through the firewall to the
server that is configured for HTTP tunneling.