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_7.0.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_7.0.0.jar file,
to your build path.
- Press the control button and 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_7.0.0.jar
file, and then click OK.
- Export your EAR file.
- Press the control button and click 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 ,
and click the server where the tunneling servlet is installed.
- Click ORB Service, then click .
- Click and
then specify com.ibm.CORBA.FragmentSize in the Name field and 0 in
the Value field.
- Click ,
and 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.