Gatekeeper Guide : AppendixGateKeeper deployment scenarios

Appendix
GateKeeper deployment scenarios
This appendix shows some common deployment scenarios in a multi-network environment with and without using GateKeeper.
TCP firewall (without GateKeeper)
Scenario 1.1: Smart Agent behind firewall
This scenario shows how to configure a client object to access a Smart Agent located behind a firewall.
Client's environment setting (using environment variables or Windows Registry):
OSAGENT_PORT
Client's properties:
vbroker.agent.addr=<osagent_host>
vbroker.agent.port=<OSAGENT_PORT>
Firewall settings:
Allow UDP packets for both directions between the client host and the Smart Agent host on port <OSAGENT_PORT>.
Allow TCP and UDP packets for both directions between the client host and the Smart Agent host on port <OSAGENT_CLIENT_HANDLER_PORT>.
Scenario 1.2: Using IIOP communication
Client's properties: none required
Server's properties:
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=683
Firewall setting:
Allow TCP packet from client host to server host on port 683.
Scenario 1.3: Using IIOP/SSL communication
Secured client's properties:
# Enabling Security Service
vbroker.security.disable=false
# Enforcing secure transport at client side
vbroker.security.alwaysSecure=true
# Setting peerAuthenticationMode
vbroker.security.peerAuthenticationMode=REQUIRE_AND_TRUST
vbroker.security.trustpointsRepository=Directory:./trustpoints
Secured server's properties:
# Enabling Security Service
vbroker.security.disable=false
# Setting SSL Layer Attributes
vbroker.security.peerAuthenticationMode=REQUIRE_AND_TRUST
vbroker.security.trustpointsRepository=Directory:./trustpoints
# Set the ssl listener port at 443
vbroker.se.iiop_tp.scms=iiop_tp,ssl
vbroker.se.iiop_tp.scm.ssl.listener.port=443
vbroker.se.iiop_tp.scm.iiop_tp.listener.type=Disabled-IIOP
The sample properties assume that valid certificate information has already been loaded into both the secured client and the secured server as in the <install_dir>/examples/vbroker/security/bank_ssl example.
Firewall setting:
Allow SSL packet from client host to server host on port 443.
Scenario 1.4: Firewall performs address translation only
Firewall setting:
Address translation: 199.10.9.6 to 101.10.2.6
Server's properties: Use only one of the following two methods.
Method 1: Using IIOP profile
vbroker.se.iiop_tp.host=101.10.2.6
vbroker.se.iiop_tp.proxyHost=199.10.9.6
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=683
Method 2: Using firewall component
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.host=101.10.2.6
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=683
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=fw
vbroker.firewall.fw.type=TCP
vbroker.firewall.fw.host=199.10.9.6
vbroker.firewall.fw.iiop_port=683
vbroker.firewall.fw.hiop_port=0
Note
Specify a real port (for example, iiop_port=683) when there is no port translation, and 0 (for example, hiop_port=0) if the listener port is disabled.
Scenario 1.5: Firewall performs port translation only
Firewall setting:
Port translation: 1683 to 683
Server's properties: Use only one of the following two methods.
Method 1: Using IIOP profile
vbroker.se.iiop_tp.host=101.10.2.6
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=683
vbroker.se.iiop_tp.scm.iiop_tp.listener.proxyPort=1683
Method 2: Using firewall component
vbroker.se.iiop_tp.host=101.10.2.6
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=683
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=fw
vbroker.firewall.fw.type=TCP
vbroker.firewall.fw.host=101.10.2.6
vbroker.firewall.fw.iiop_port=1683
vbroker.firewall.fw.hiop_port=0
Note
Specify real host when there is no address translation.
When method 2 is used, add the following to the client's properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
Scenario 1.6: Firewall performs both address and port translations
Combine the settings in Scenarios 1.4 and 1.5 when the firewall performs both address and port translation.
Note
For firewall component method, specify the firewall once combining both the fake host and fake port into the same firewall entry like the following:
vbroker.se.iiop_tp.host=101.10.2.6
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=683
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=fw
vbroker.firewall.fw.type=TCP
vbroker.firewall.fw.host=199.10.9.6
vbroker.firewall.fw.iiop_port=1683
vbroker.firewall.fw.hiop_port=0
Note
For secure connection with NAT (Network Address Translation), use the security properties settings in Scenario 1.3.
Scenario 1.7: Callback without NAT
Refer to Scenario 1.2 for forward communication settings.
Client's properties:
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=16001
Firewall setting:
Allow TCP packet from server host to client host on port 16001.
Scenario 1.8: Callback with NAT
Refer to Scenario 1.2 for forward communication settings.
Firewall setting:
Address translation: 130.129.129.10 to 99.29.29.10 for packets from server network to client network. Port translation: 16100 to 16001 for packets from server network to client network.
Client's properties:
vbroker.se.iiop_tp.host=99.29.29.10
vbroker.se.iiop_tp.proxyHost=130.129.129.10
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=16001
vbroker.se.iiop_tp.scm.iiop_tp.listener.proxyPort=16100
Scenario 1.9: Bi-directional communication
Use the settings in Scenario 1.2, 1.3, 1.4, 1.5, or 1.6 with the following additional settings to enable bi-directional communication.
In the figure above, the same connections are used for both forward and reverse communications paths.
Client's Properties:
vbroker.orb.enableBiDir=client
Server's Properties:
vbroker.orb.enableBiDir=server
Scenario 1.10: Multiple firewalls in front of server
This scenario shows two firewalls in front of the server host. It can be extended similarly to more than two firewalls.
Both firewalls do not perform NAT
When both firewalls do not perform NAT, configure both the firewalls to allow TCP packets (for IIOP communication) on port Ps.
Only Firewall 1 performs NAT
Firewall1 performs the following NAT:
Server's properties: Use only one of the following two methods.
Method 1: Using IIOP profile
vbroker.se.iiop_tp.host=<Hs>
vbroker.se.iiop_tp.proxyHost=<H1>
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<Ps>
vbroker.se.iiop_tp.scm.iiop_tp.listener.proxyPort=<P1>
Method 2: Using firewall component
vbroker.se.iiop_tp.host=<Hs>
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<Ps>
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=fw1
vbroker.firewall.fw1.type=TCP
vbroker.firewall.fw1.host=<H1>
vbroker.firewall.fw1.iiop_port=<P1>
vbroker.firewall.fw1.hiop_port=0
Only firewall2 performs NAT
Firewall2 performs the following NAT:
Server's properties: Use only one of the following two methods.
Method 1: Using IIOP profile
vbroker.se.iiop_tp.host=<Hs>
vbroker.se.iiop_tp.proxyHost=<H2>
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<Ps>
vbroker.se.iiop_tp.scm.iiop_tp.listener.proxyPort=<P2>
Method 2: Using firewall component
vbroker.se.iiop_tp.host=<Hs>
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<Ps>
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=fw2
vbroker.firewall.fw2.type=TCP
vbroker.firewall.fw2.host=<H2>
vbroker.firewall.fw2.iiop_port=<P2>
vbroker.firewall.fw2.hiop_port=0
Both firewalls perform NAT
Firewall1 performs the following NAT:
Server's properties: Use only one of the following two methods.
Method 1: Using IIOP profile
vbroker.se.iiop_tp.host=<Hs>
vbroker.se.iiop_tp.proxyHost=<H1>
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<Ps>
vbroker.se.iiop_tp.scm.iiop_tp.listener.proxyPort=<P1>
Method 2: Using firewall component
vbroker.se.iiop_tp.host=<Hs>
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<Ps>
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=fw1
vbroker.firewall.fw1.type=TCP
vbroker.firewall.fw1.host=<H1>
vbroker.firewall.fw1.iiop_port=<P1>
vbroker.firewall.fw1.hiop_port=0
Note
The NAT information of Firewall2 does not need to be configured. The proxyHost and proxyPort specify only the first NAT fake host and fake port. For the firewall component and the firewall path, only specify the first NAT device.
GateKeeper deployment
Scenario 2.1: GateKeeper as Web Server
GateKeeper can act as a Web Server to serve HTML pages, client applet and IOR files.
Set the GateKeeper HTTP listener using the following GateKeeper's properties:
vbroker.se.exterior.scms=ex-iiop,ex-hiop
vbroker.se.exterior.scm.ex-hiop.listener.port=8088
From the web browser of the client host,
http://gatekeeper:8088/ClientApplet.html
http://gatekeeper:8088/gatekeeper.ior
Configure the client applet (ClientApplet.html) using the following example:
<applet archive=vbjorb.jar code=”ClientApplet.class” width=”200” height=”80”>
<param name=”org.omg.CORBA.ORBClass” value=”com.inprise.vbroker.orb.ORB”>
<param name=”vbroker.orb.alwaysTunnel” value=”true”>
<param name=”vbroker.orb.gatekeeper.ior” value=”http://gatekeeper:8088/gatekeeper.ior”>
</applet>
Any additional client properties needed can be set similarly using param name and value.
Scenario 2.2: GateKeeper as IIOP Proxy
Client's properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.alwaysProxy=true
GateKeeper's properties:
vbroker.se.exterior.scm.ex-iiop.listener.port=683
vbroker.se.exterior.scm.ex-hiop.listener.port=8088
Server's properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.exportFirewallPath=true
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk
vbroker.firewall.gk.type=PROXY
vbroker.firewall.gk.ior=http://gatekeeper:8088/gatekeeper.ior
If the client is an applet that wants to use IIOP instead of HTTP Tunneling, use the following configuration, do not specify the property <param name=”vbroker.orb.alwaysTunnel” value=”true”>:
<applet archive=vbjorb.jar code=”ClientApplet.class” width=”200” height=”80”>
<param name=”org.omg.CORBA.ORBClass” value=”com.inprise.vbroker.orb.ORB”>
<param name=”vbroker.orb.alwaysProxy” value=”true”>
<param name=”vbroker.orb.gatekeeper.ior” value=”http://gatekeeper:8088/gatekeeper.ior”>
</applet>
Scenario 2.3: HTTP Tunneling Connection
Client's properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init,com.inprise.vbroker.HIOP.Init
vbroker.orb.alwaysTunnel=true
vbroker.orb.alwaysProxy=true
vbroker.orb.gatekeeper.ior=http://gatekeeper:8088/gatekeeper.ior
GateKeeper's properties:
vbroker.se.exterior.scm.ex-hiop.listener.port=8088
vbroker.se.exterior.scm.ex-iiop.listener.port=683
Server's properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk
vbroker.firewall.gk.type=PROXY
vbroker.firewall.gk.ior=http://gatekeeper:8088/gatekeeper.ior
vbroker.orb.exportFirewallPath=true
If the client is an applet that wants to use HTTP Tunneling, use the following configuration:
<applet archive=vbjorb.jar code=”ClientApplet.class” width=”200” height=”80”>
<param name=”org.omg.CORBA.ORBClass” value=”com.inprise.vbroker.orb.ORB”>
<param name=”vbroker.orb.alwaysTunnel” value=”true”>
<param name=”vbroker.orb.gatekeeper.ior” value=”http://gatekeeper:8088/gatekeeper.ior”>
</applet>
Scenario 2.4: Secure connection (SSL)
Client's properties:
# Firewall related properties
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.alwaysProxy=true
# Set SSL related properties
vbroker.security.disable=false
vbroker.security.wallet.type=Directory:./identities
vbroker.security.wallet.identity= paul
vbroker.security.wallet.password= Paul$$$$
vbroker.security.trustpointsRepository=Directory:./trustpoints
GateKeeper's properties:
vbroker.se.exterior.scms=ex-iiop,ex-ssl
vbroker.se.exterior.scms.ex-iiop.listener.type=Disabled-IIOP
vbroker.se.exterior.scms.ex-hiop.listener.port=8088
vbroker.se.exterior.scms.ex-ssl.listener.port=443
# Set SSL related properties
vbroker.security.disable=false
vbroker.security.wallet.type=Directory:./identities
vbroker.security.wallet.identity= kevin
vbroker.security.wallet.password= Kevin$$$$
vbroker.security.trustpointsRepository=Directory:./trustpoints
vbroker.se.iiop_tp.scm.ssl.listener.port=<server SSL: listener port>
Server's properties:
# Firewall related properties
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.exportFirewallPath=true
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk
vbroker.firewall.gk.type=PROXY
vbroker.firewall.gk.ior=http://gatekeeper:8088/gatekeeper.ior
# SSL related properties
vbroker.security.disable=false
vbroker.security.wallet.type=Directory:./identities
vbroker.security.wallet.identity= kevin
vbroker.security.wallet.password= Kevin$$$
vbroker.security.trustpointsRepository=Directory:./trustpoints
vbroker.se.iiop_tp.scms=iiop_tp,ssl
vbroker.se.iiop_tp.scm.ssl.listener.port=<server SSL listener port>
vbroker.se.iiop_tp.scm.iiop_tp.listener.type=Disabled-IIOP
Scenario 2.5: Secure HTTP Tunneling
Use the client and server settings in Scenario 2.4 and add the following to the client's properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init,
com.inprise.vbroker.HIOP.Init
com.inprise.security.Init,
com.inprise.security.hiops.Init
vbroker.orb.alwaysTunnel=true
GateKeeper's properties:
vbroker.orb.dynamicLibs=com.inprise.security.Init,
com.inprise.vbroker.gatekeeper.ssl.Init,
com.inprise.security.hiops.Init
vbroker.se.exterior.scms=ex-IIOP,ex-hiop,ex-hiops
vbroker.se.exterior.scm.ex-iiop.listener.type=Disabled-IIOP
vbroker.se.exterior.scm.ex-hiops.listener.port=443
vbroker.se.exterior.scm.ex-hiop.listener.port=8088
vbroker.security.wallet.type=Directory:./identities
vbroker.security.wallet.identity=Kevin
vbroker.security.wallet.password=Kevin$$$
vbroker.security.secureTransport=true
vbroker.security.trustpointsRepository=Directory:./trustpoints
vbroker.security.peerAuthenticationMode=none
Scenario 2.6: Callback connection (for VisiBroker 3.x style)
Refer to Scenario 2.2 for forward communication settings.
Set the following client's property:
vbroker.se.iiop_tp.scm.iiop_tp.type=Callback-IIOP
vbroker.se.iiop_tp.scm.iiop_tp.listener.gatekeeper=http://gk_host:8088/gatekeeper.ior
Enable GateKeeper callback (VisiBroker 3.x style) using the following GateKeeper's properties:
vbroker.gatekeeper.callbackEnabled=true
vbroker.gatekeeper.backcompat.callback=true
vbroker.gatekeeper.backcompat.callback.listeners=iiop
vbroker.gatekeeper.backcompat.callback.listener.iiop.port=<exterior callback port>
vbroker.gatekeeper.backcompat.callback.listener.iiop.type=IIOPCallback
The interior port in-iiop is automatically enabled when callback is enabled. Only for secured callback, you need to add the SCM for in-ssl, ex-ssl and ex-hiops as required.
Scenario 2.7: Bi-directional communication
Use the settings in Scenario 2.2, 2.3, 2.4, or 2.5 with the following additional settings to enable bi-directional communication.
Client's Properties:
vbroker.orb.enableBiDir=client
Server's Properties:
vbroker.orb.enableBiDir=server
GateKeeper's Properties:
vbroker.orb.enableBiDir=both
Scenario 2.8: Pass-through connection
Use the settings in Scenario 2.2 or 2.4 with the following additional settings to enable pass-through connection.
Client's Properties:
vbroker.orb.proxyPassthru=true
GateKeeper's Properties:
vbroker.gatekeeper.enablePassthru=true
Scenario 2.9: GateKeeper in dual-homed host configuration
Use the following GateKeeper's properties to configure:
vbroker.se.exterior.host=199.10.9.5
vbroker.se.interior.host=101.10.2.6
vbroker.se.exterior.scm.ex-iiop.listener.port=<exterior IIOP port>
vbroker.se.exterior.scm.ex-hiop.listener.port=<exterior HIOP port>
vbroker.se.interior.scm.in-iiop.listener.port=<interior IIOP port>
GateKeeper with server-side firewall
Note
Routers can also perform the function of a firewall.
Firewall in front of GateKeeper
Scenario 3.1: Firewall performs packet-filtering without NAT
GateKeeper's properties:
vbroker.se.exterior.scm.ex-iiop.listener.port=683
vbroker.se.exterior.scm.ex-hiop.listener.port=8088
Firewall setting:
Allow routing of TCP packets on port 683 and HTTP packets on port 8088 from the external network to the internal network.
Server's properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk
vbroker.firewall.gk.type=PROXY
vbroker.firewall.gk.ior=http://101.10.2.10:8088/gatekeeper.ior
Scenario 3.2: Firewall performs NAT
Firewall NAT setting:
Address translation: 199.10.9.10 to 101.10.2.10 Port translations: 10683 to 683 and 8000 to 8088
There are two methods for specifying a NAT on a firewall in front of GateKeeper (use only one of the following two methods):
Using GateKeeper's proxyHost and proxyPort configuration
GateKeeper's properties:
vbroker.se.exterior.host=101.10.2.10
vbroker.se.exterior.proxyHost=199.10.9.10
vbroker.se.exterior.scm.ex-iiop.listener.port=683
vbroker.se.exterior.scm.ex-iiop.listener.proxyPort=10683
vbroker.se.exterior.scm.ex-hiop.listener.port=8088
vbroker.se.exterior.scm.ex-hiop.listener.proxyPort=8000
Server's properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk
vbroker.firewall.gk.type=PROXY
vbroker.firewall.gk.ior=http://101.10.2.10:8088/gatekeeper.ior
GateKeeper's properties:
vbroker.se.exterior.host=101.10.2.10
vbroker.se.exterior.scm.ex-iiop.listener.port=683
vbroker.se.exterior.scm.ex-hiop.listener.port=8088
Server's properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=fw,gk
vbroker.firewall.fw.type=TCP
vbroker.firewall.fw.host=199.10.9.10
vbroker.firewall.fw.iiop_port=10683
vbroker.firewall.fw.hiop_port=8000
vbroker.firewall.gk.type=PROXY
vbroker.firewall.gk.ior=http://101.10.2.10:8088/gatekeeper.ior
Scenario 3.3: Callback connection (for VisiBroker 3.x style)
Refer to Scenario 3.1 or 3.2 for forward communication settings.
Set the following client's property:
vbroker.se.iiop_tp.scm.iiop_tp.type=Callback-IIOP
vbroker.se.iiop_tp.scm.iiop.listener.gatekeeper=http://gk_host:8088/gatekeeper.ior
Enable GateKeeper callback (VisiBroker 3.x style) and specify the callback port using the following properties:
vbroker.gatekeeper.callbackEnabled=true
vbroker.gatekeeper.backcompat.callback=true
vbroker.gatekeeper.backcompat.callback.host=101.10.2.10
vbroker.gatekeeper.backcompat.callback.listeners=iiop
vbroker.gatekeeper.backcompat.callback.listener.iiop.port=2683
vbroker.gatekeeper.backcompat.callback.listener.iiop.type=IIOPCallback
The firewall must allow the client to establish a callback connection (TCP protocol) to GateKeeper using port 2683.
Configure the interior ports using the following GateKeeper's properties:
vbroker.se.interior.scm.in-iiop.listener.port=16000
If the firewall performs NAT on the GateKeeper's host and callback port (address translation:199.10.9.10 to 101.10.2.10 and port translation: 12683 to 2683), add the following into GateKeeper's properties:
vbroker.gatekeeper.backcompat.callback.proxyHost=199.10.9.10
vbroker.gatekeeper.backcompat.callback.listener.iiop.proxyPort=12683
Scenario 3.4: Bi-directional communication
Use the settings in Scenario 3.1 or 3.2 with the following additional settings to enable bi-directional communication.
Client's Properties:
vbroker.orb.enableBiDir=client
Server's Properties:
vbroker.orb.enableBiDir=server
GateKeeper's Properties:
vbroker.orb.enableBiDir=both
Scenario 3.5: Pass-through connection
Use the settings in Scenario 3.1 or 3.2 with the following additional settings to enable pass-through connection.
Client's Properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.proxyPassthru=true
GateKeeper's Properties:
vbroker.gatekeeper.enablePassthru=true
vbroker.gatekeeper.passthru.inPortMin=<in_min_port>
vbroker.gatekeeper.passthru.inPortMax=<in_max_port>
Firewall setting:
Caution
Allow routing of TCP packets on port range <in_min_port> to <in_max_port> from the client host to the GateKeeper. The firewall must not perform port translation on this range of ports.
Firewall in front and behind of GateKeeper
GateKeeper is deployed in the Demilitarized Zone (DMZ) while the servers are deployed in the internal network.
Note
Refer to the previous section for a configuration related to a firewall in front of GateKeeper. This section concentrates on the configuration related to the firewall between the GateKeeper and servers.
Scenario 4.1: Configuring firewall behind GateKeeper
Use the settings in Scenario 3.1 or 3.2 to configure the communication between clients and GateKeeper. The settings described here should be used in conjunction to the settings in Scenario 3.1 or 3.2.
Specify the server IIOP listener port using the following server's properties:
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=683
Configure Firewall2 to allow IIOP packet (TCP protocol) from GateKeeper to the server host on port 683.
Scenario 4.2: Firewall behind GateKeeper performs NAT
Use the settings in Scenario 3.1 or 3.2 to configure the communication between clients and GateKeeper. The settings described here should be used in conjunction to the settings in Scenario 3.1 or 3.2.
Firewall2 NAT setting:
Address translation: 199.10.9.10 to 101.10.2.10
Ports translation: 1683 to 683
There are two methods for specifying NAT on Firewall2. Use only one of the following two methods.
Server's properties:
Method 1: Using IIOP profile
vbroker.se.iiop_tp.host=101.10.2.6
vbroker.se.iiop_tp.proxyHost=199.10.9.6
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=683
vbroker.se.iiop_tp.scm.iiop_tp.listener.proxyPort=1683
Method 2: Using firewall component
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk,fw2
vbroker.firewall.gk.type=PROXY
vbroker.firewall.gk.ior=http://gatekeeper:8088/gatekeeper.ior
vbroker.firewall.fw2.type=TCP
vbroker.firewall.fw2.host=199.10.9.6
vbroker.firewall.fw2.iiop_port=1683
vbroker.firewall.fw2.hiop_port=0
Scenario 4.3: Callback connection (for VisiBroker 3.x style)
Use the settings in Scenario 3.3 callback connection between client and GateKeeper.
Configure the interior ports using the following GateKeeper's properties:
vbroker.se.interior.scm.in-iiop.listener.port=16000
Firewall2 must allow the server to communicate with GateKeeper on port 16000 using TCP protocol.
If Firewall2 performs the following NAT for packets routed from the server to GateKeeper:
Address Translation: 121.100.2.19 to 101.10.2.10Port Translation: 161000 to 16000
Then add the following properties to the GateKeeper's properties:
vbroker.se.interior.host=101.10.2.10
vbroker.se.interior.proxyHost=121.100.2.19
vbroker.se.interior.scm.in-iiop.listener.port=16000
vbroker.se.interior.scm.in-iiop.listener.proxyPort=16100
Scenario 4.4: Bi-directional communication
Use the settings in Scenario 4.1 or 4.2 with the following additional settings to enable bi-directional communication.
Client's Properties:
vbroker.orb.enableBiDir=client
Server's Properties:
vbroker.orb.enableBiDir=server
GateKeeper's Properties:
vbroker.orb.enableBiDir=both
Scenario 4.5: Pass-through connection
Use the settings in Scenario 4.1 or 4.2 with the following additional settings to enable pass-through connection.
Client's Properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.proxyPassthru=true
GateKeeper's Properties:
vbroker.gatekeeper.enablePassthru=true
vbroker.gatekeeper.passthru.inPortMin=<in_min_port>
vbroker.gatekeeper.passthru.inPortMax=<in_max_port>
vbroker.gatekeeper.passthru.outPortMin=<out_min_port>
vbroker.gatekeeper.passthru.outPortMax=<out_max_port>
Server's Properties:
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<server IIOP port>
Caution
The value of <server IIOP port> must fall in the range of <out_min_port> and <out_max_port>.
Configure Firewall1 to allow routing of TCP packets in port range <in_min_port> to <in_max_port> from the client host to the GateKeeper. Configure Firewall2 to allow routing of TCP packets in port range <out_min_port> to <out_max_port> from the GateKeeper to the server host. The firewalls must not perform port translation on these ports.
Scenario 4.6: Smart Agent in internal network
Use the settings in Scenario 1.1 assuming GateKeeper is the client.
GateKeeper with client-side firewall
Scenario 5.1: Firewall allows IIOP
The client-side firewall allows clients from the internal network to send IIOP messages (TCP protocol) to the external network.
Refer to Scenarios 3.x replacing the server-side firewall in front of GateKeeper with a client-side firewall. As GateKeeper is outside the client domain, the client-side administrator who control the firewall, usually does not have the authority to modify the GateKeeper's configuration. The administrator has to collect the GateKeeper's listener ports information to configure the client-side firewall accordingly.
Scenario 5.2: Firewall allows HTTP only
The client-side firewall allows clients from the internal network to send HTTP messages only to the external network. IIOP message will be blocked by the firewall. Therefore, clients have to use HTTP tunneling to communicate with a GateKeeper outside the client-side firewall.
Set the following client's property to force the client to always use HTTP tunneling.
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.alwaysTunnel=true
Note
HTTP tunneling does not support the VisiBroker 3.x style callback. If callback is required, use a bi-directional connection. Pass-through connection is also not available with HTTP tunneling.
GateKeeper load balancing and fault-tolerance
Scenario 6.1: Using multiple GateKeepers for fault-tolerance
Instead of relying on a single GateKeeper, you can deploy multiple GateKeepers for fault-tolerance. Assign more than one GateKeeper to a server to create redundancy.
The server's properties in this example are as follows:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p1,p2
vbroker.firewall-path.p1=gk1
vbroker.firewall.gk1.type=PROXY
vbroker.firewall.gk1.ior=http://gk1_host:8088/gatekeeper.ior
vbroker.firewall-path.p2=gk2
vbroker.firewall.gk2.type=PROXY
vbroker.firewall.gk2.ior=http://gk2_host:8088/gatekeeper.ior
The following property is required for both GK1 and GK2:
vbroker.orb.dynamicLibs=com.inprise.vbroker.gatekeeper.ext.Init
Clients can use either GK1 or GK2 to communicate with the server. When one GateKeeper is down, the client can use the other one to communicate with the server.
Scenario 6.2: Master/Slave configuration for load balancing
The figure above shows a master/slave GateKeeper configuration with GK1 as the master GateKeeper while GK2 and GK3 are the slave GateKeepers
GateKeeper GK1 properties (master):
vbroker.orb.dynamicLibs=com.inprise.vbroker.gatekeeper.ext.Init
vbroker.gatekeeper.load.slaves=gk2,gk3
vbroker.gatekeeper.load.slave.gk2=http://gk2_host:8088/gatekeeper.ior
vbroker.gatekeeper.load.slave.gk3=http://gk3_host:8088/gatekeeper.ior
No additional properties are required for slave GateKeepers GK1 and GK2:
Server's Properties (specify only the master GateKeeper):
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk1
vbroker.firewall.gk1.type=PROXY
vbroker.firewall.gk1.ior=http://gk1_host:8088/gatekeeper.ior
If the client is not able to obtain the server's IOR directly, then the client can specify a GateKeeper to contact using the following property:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.gatekeeper.ior=http://gk1_host:8088/gatekeeper.ior
This configuration also provides fault-tolerance. For each connecting client, the master GateKeeper assigns the next slave GateKeeper in turn to serve the client, but if that slave GateKeeper is down, the client will come back to the master GateKeeper to get assigned to the next available slave GateKeeper, and so on, until the client obtains a usable GateKeeper.
The master GateKeeper actually keeps a list of available GateKeepers, which it can assign to a connecting client. The list contains all slave GateKeepers as well as the master GateKeeper itself. Therefore, when its turn comes around, the master GateKeeper will assign itself to a client.
When the following property is set on the master GateKeeper, the master GateKeeper is not included in the list.
vbroker.gatekeeper.load.balancer=master
In the case that all slave GateKeepers are down, in order to prevent clients from coming back to the master GateKeeper for obtaining a usable GateKeeper again and again infinitely, the following property should be set on the client side:
vbroker.orb.rebindForward=N
where N must be less than the number of slave GateKeepers.
When the master GateKeeper itself is down, the rebind mechanism on the client ORB will make all clients connect through the first available slave GateKeeper, there will be no load balancing in this situation as the load balance functionality is in the master GateKeeper and the master is down. However, fault tolerance is preserved because clients still can get through and connect to the servers.
Scenario 6.3: Multiple instances of same server for load balancing
You can deploy multiple instances of the same server to provide load balancing and fault-tolerance for the server. For load balancing, the GateKeeper will direct the request to the multiple servers using a round-robin mechanism. For fault-tolerance, if one server is down, another server can continue to provide the same service.
Add the following property to the GateKeeper:
vbroker.orb.dynamicLibs=com.inprise.vbroker.gatekeeper.ext.Init
Server1 and Server2 properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk
vbroker.firewall.gk.type=PROXY
vbroker.firewall.gk.ior=http://gk_host:8088/gatekeeper.ior
GateKeeper chaining
Scenario 7.1: Server-side chaining
Use the following server's properties to specify the server-side GateKeeper chaining:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk1,gk2
vbroker.firewall.gk1.type=PROXY
vbroker.firewall.gk1.ior=http://gk1_host:8088/gatekeeper.ior
vbroker.firewall.gk2.type=PROXY
vbroker.firewall.gk2.ior=http://gk2_host:8088/gatekeeper.ior
When the client obtains the server's IOR, it will be able to use the GateKeeper chaining to communicate with the server.
Scenario 7.2: Client-side chaining
Client's Properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.gatekeeper.ior=http://GK1:8088/gatekeeper.ior
GK1's Properties:
vbroker.orb.gatekeeper.ior=http://GK2:8088/gatekeeper.ior
Note
In order for the client to communicate with the server using the chained GateKeepers, the last GateKeeper on the chain (GK2) must be able to obtain the server's IOR.
Scenario 7.3: Both server-side and client-side chaining
Client's Properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.gatekeeper.ior=http://gk_host:8088/gatekeeper.ior
Server's Properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.p=gk2
vbroker.firewall.gk2.type=PROXY
vbroker.firewall.gk2.ior=http://gk2_host:8088/gatekeeper.ior
If GK1 always connect to GK2, you can chain GK1 to GK2 statically using the following GK1 property:
vbroker.orb.gatekeeper.ior=http://gk2_host:8088/gatekeeper.ior
Otherwise, GK1 must be able to obtain the IOR of the server or GK2 using a Smart Agent or Naming Services.
Scenario 7.4: Callback communication (VisiBroker 3.x style)
Set the following properties to allow VisiBroker 3.x style callback communication.
Client's Properties:
vbroker.orb.alwaysProxy=true
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.se.iiop_tp.scm.iiop_tp.listener.type=Callback-IIOP
vbroker.se.iiop_tp.scm.iiop_tp.listener.gatekeeper=http://gk1_host:8088/gatekeeper.ior
GK1 and GK2 properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.gatekeeper.ext.Init
vbroker.gatekeeper.callbackEnabled=true
vbroker.gatekeeper.backcompat.callback=true
vbroker.gatekeeper.backcompat.callback.listeners=iiop
vbroker.gatekeeper.backcompat.callback.listener.iiop.type=IIOPCallback
vbroker.gatekeeper.backcompat.callback.listener.iiop.port=
<exterior callback port>
vbroker.gatekeeper.backcompat.callback.host=<GK exterior IP address>
vbroker.se.interior.scm.in-iiop.listener.port=<interior port>
Server's Properties:
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<IIOP listener port>
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.exportFirewallPath=true
vbroker.se.iiop_tp.firewallPaths=p
vbroker.firewall-path.intranet=gk1,gk2
vbroker.firewall.gk1.type=PROXY
vbroker.firewall.gk1.ior=http://gk1_host:8088/gatekeeper.ior
vbroker.firewall.gk2.type=PROXY
vbroker.firewall.gk2.ior=http://gk2_host:8088/gatekeeper.ior
Scenario 7.5: Bi-directional connection
Refer to Scenario 7.1, 7.2, or 7.3.
Add the following additional settings to enable bi-directional communication.
Client's Properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.enableBiDir=client
Server's Properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.enableBiDir=server
GK1 and GK2 Properties:
vbroker.orb.enableBiDir=both
Scenario 7.6: Pass-through connection
Refer to the diagrams in Scenario 7.1, 7.2, or 7.3.
Client's Properties:
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init
vbroker.orb.proxyPassthru=true
GK1 and GK2 Properties:
vbroker.gatekeeper.enablePassthru=true
vbroker.gatekeeper.passthru.inPortMin=<in_min_port>
vbroker.gatekeeper.passthru.inPortMax=<in_max_port>
vbroker.gatekeeper.passthru.outPortMin=<out_min_port>
vbroker.gatekeeper.passthru.outPortMax=<out_max_port>
Server's Properties:
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<server IIOP port>
Note
The value of <server IIOP port> must fall in the range of <out_min_port> and <out_max_port> of GK2. The range of <in_min_port> and <in_max_port> of GK2 must fall in the range of <out_min_port> and <out_max_port> of GK1.
If there is a firewall between any of the hosts, refer to the following table for the ports to be opened.
GK2 <out_min_port> and <out_max_port>
Caution
The firewalls must not perform any port translation on the pass-through ports.
Using VisiBroker in a multiple firewall/subnet environment
VisiBroker can be used in multiple firewall scenarios. In general, VisiBroker provides two different approaches to cross firewalls.
First, the Network Address Translation (also called TCP firewalls) can be configured using the following properties:
vbroker.se.iiop_tp.host=www.realdomain.com
vbroker.se.iiop_tp.proxyHost=www.fakedomain.com
vbroker.se.iiop_tp.scm.iiop_tp.listener.port=25000
vbroker.se.iiop_tp.scm.iiop_tp.listener.proxyPort=32000
In the above-mentioned configuration, the real host / port information is lost in the IOR, which means only the fake host /port is available in the IOR. Another commonly deployed TCP firewall configuration is a server-side configuration. Since this configuration is an ORB built-in mechanism, it also applies to all types of services (for example GateKeeper, Naming Service, and so forth).
vbroker.orb.exportFirewallPath=true
vbroker.se.iiop_tp.firewallPaths =Queen
vbroker.firewall-path.Queen=Atlantic
vbroker.firewall-path.Atlantic.type=TCP
vbroker.firewall-path.Atlantic.host=www.fakedomain.com
vbroker.firewall-path.Atlantic.iiop_port=32000
vbroker.firewall-path.Atlantic.hiop_port=32003
vbroker.firewall-path.Atlantic.ssl_port=32004
The advantage of the technique above is that the configuration information is not lost. The internal client can connect to the servers directly using the real IP host / port information. The risk involved with this configuration, however, is that both the IP host /port (real and fake) are exposed in the generated IOR file.
Second, GateKeeper can be run on the firewall server to act as a GIOP proxy server. Various mechanisms are available in GateKeeper that are designed for different purposes. For example:
Normal mode: Used when the firewalls can allow at least one port for the GIOP Proxy Server (such as GateKeeper). It is an automatic mode which can switch to HTTP tunneling if required.
Pass through mode: Used when the firewalls can allow a range of ports and packets exchanged between the client and server that is not to be interpreted by GateKeeper. In such a scenario, GateKeeper will act as a resource manager only. GateKeeper acts as a resource manager because it allocates IP ports to be used by the clients.
HTTP tunneling: Used when the firewalls allow only HTTP traffic. In such a scenario, the GIOP Proxy Server cannot be run in the firewall. Instead, an HTTP proxy server sits before GateKeeper. The client ORB has a built in mechanism to convert GIOP messages into HTTP messages which will be sent to the HTTP proxy server or the firewall. Then, the HTTP proxy server (or the applicable firewall) forwards the HTTP messages to GateKeeper. Additionally, GateKeeper converts the HTTP messages into GIOP messages and forwards it to the required target (such as server or another GateKeeper). This configuration is also useful in a client-side configuration when outgoing HTTP traffic is allowed by the firewall, but other types of TCP connections are not allowed.
Note
Multiple firewalls may need a combination of the above configuration techniques. Basically, the use of multiple firewalls is a deployment issue and, therefore, all possible combinations cannot be covered in this document. Some general guidelines are.
Firewall and Smart Agent
Within a firewall architecture, the Smart Agent is not expected to run on the firewall host. Instead, the Smart Agent can be run within the internal network. Usually, the Smart Agent should not be exposed to the external network because of security reasons. The Smart Agent uses an IPv4 UDP broadcast message to advertise itself. Since the firewall / routers can block broadcast messages from being forwarded to the next hop in the network, the Smart Agent is usually visible only in the local network. If the Smart Agent needs to be accessible from an external network, you must open a specific port on the firewall.
The following environment variables are used by the Smart Agent:
The VisiBroker-ORB requires the OSAGENT_PORT environment variable to be set to register and query CORBA objects using the Smart Agent. The default value of OSAGENT_PORT is 14000. By setting OSAGENT_PORT to an appropriate TCP/IP port, you can define a virtual domain. One can run any number of Smart Agents in a given subnet. Setting different OSAGENT_PORT values will create different domains, which means CORBA objects registered in one Smart Agent domain will not be visible to CORBA client querying from a different domain.
Set the following TCP/IP address or port to be used by CORBA application to reach the Smart Agent:
If the client, server, or GateKeeper does not require the use of the Smart Agent, set the following property in the respective property files to disable it:
vbroker.agent.enableLocator=false
GateKeeper is run on a multi-homed (or firewall) host. The Smart Agent can be run either on the multi-homed host on in the internal network. GateKeeper can be configured to use a designated Smart Agent using the following properties (for example):
vbroker.agent.addr=143.186.142.21
vbroker.agent.port=25873
The server in the internal network should register itself to the same Smart Agent as the GateKeeper if your client program expects GateKeeper to query the server objects to get the IOR using the following properties (for example).
vbroker.agent.addr=143.186.142.21
vbroker.agent.port=25873
GateKeeper can use only one Smart Agent domain at a time. The Smart Agent domain is determined by setting the OSAGENT_PORT value or the vbroker.agent.port property. All servers accessible through GateKeeper should register to the same Smart Agent domain or to the Naming Service. It is recommended to run the Smart Agent on the same subnet as GateKeeper in the internal network.
The following ports are required by the Smart Agent:
1
OSAGENT_PORT (UDP type)
2
3
The OSAGENT_PORT used by the ORB applications is a UDP port. The only TCP type of port (also known as the OSAGENT_CLIENT_HANDLER_PORT) used by the Smart Agent is assigned to the Location Service. The OSAGENT_CLIENT_HANDLER_PORT of the UDP type is used by the Smart Agent itself. Please note that OSAGENT_CLIENT_HANDLER_PORT should be set only on those hosts where the Smart Agent is running.
Using the Smart Agent with a firewall
The Smart Agent has some built-in fail-over and load-balancing capabilities. The domain of the Smart Agent is defined by the OSAGENT_PORT in use. If an ORB application (such as a server) is registered to one of the Smart Agents in a given domain (the Smart Agent domain), other ORB applications (such as a client program) can query the server objects in that domain from any of Smart Agents in the same domain. Thus, Smart Agents can query within a domain to locate a server object without making the client application aware of the process. Therefore, if one Smart Agent fails, the ORB application can find another Smart Agent in the same domain, register itself again, and proceed.
By design, the load-balancing capability of Smart Agents is not extended to firewalls because each firewall has unique behavior. For example, a NAT (Network Address Translation) device is a type of firewall which changes the IP address/port. The Smart Agent is not designed to handle NAT scenarios. Also, some firewalls may allow only specific types of packets, others may require security and encryption, and some may not allow DNS lookups. Therefore, the Smart Agent should not be used in any kind of firewall or NAT configuration.
Although the Smart Agent is not designed to be used in a firewall scenario, there are a few steps to follow if an application must access a Smart Agent sitting behind the firewall. The following steps, however, apply to inter-departmental firewalls only:
1
Open the OSAGENT_PORT and OSAGENT_CLIENT_HANDLER_PORT on the firewall. Certain firewalls may require that you set static forwarding routes so that the packets can reach the Smart Agent. All the intermediate firewalls between the applications should open these ports as well. Since firewalls may be on a multi-homed host, edit the localaddr (located, for example, in the <instal_dir>var/defaults/adm/properties/services/osagentfile folder) and set OSAGENT_LOCAL_ADDR_FILE to specify all the interfaces Smart Agent should bind to listen for request packets.
2
Set the Smart Agent IP address in the agentaddr file to allow the Smart Agent on one network to contact a Smart Agent on another network.
3
Set OSAGENT_PORT and OSAGENT_CLIENT_HANDLER_PORT on all hosts from where ORB applications may be launched. Please note that these ports should be the same as those opened on the firewalls.
Note
Even though it is possible to use the Smart Agent with the above settings, such usage is not recommend because this type of configuration may work with some firewalls, but will not work with all types of firewalls.
If Smart Agent fails
If the Smart Agent fails, the ORB application is expected to switch to another Smart Agent in the same subnet. Because the Smart Agent OSAGENT_PORT is already fixed, the ORB application sends a UDP broadcast to locate another Smart Agent. If there is a firewall, the ORB application should have access to reach another host where the Smart Agent is running. The ORB application may not have the knowledge of the location of an alternative Smart Agent, so it can't do much. If the Smart Agent starts up again on the same host, the client may be able to contact it. Basically, it is important to understand that the Smart Agent uses a UDP broadcast-based technology. Some firewalls and routers may not forward UDP broadcasts and this is one of the reasons why the Smart Agent cannot be used across firewalls. Another Smart Agent, however, can be used if a Smart Agent in the same subnet fails.
Client behavior for using the Smart Agent
A client ORB application can be configured to use a specific range of ports to bind to the Smart Agent by setting the following properties:
vbroker.agent.clientPort
vbroker.agent.clientPortRange
The port range ensures that the client ORB uses the local ports in a given range only. The client port range is required because Windows/NT delays actual closure of ports resulting in limited use of the port range.
Using GateKeeper with other CORBA services
From a client's perspective, GateKeeper is transparent to all other CORBA Services. There is no distinction made between a usual server object and other CORBA services such as the Naming Service, Transaction Service, Notification Service, Event Service, and so forth.
In a server-side configuration, the server can be configured to specify the firewall component in its IOR which is identified by the client ORB and is used only when required. In such cases, the client fails over to bind to the server using GateKeeper only if a direct connection could not be established. Assuming that iiop_tp is the default server-engine used by the server, the following example shows a typical set of properties for a firewall configuration:
vbroker.orb.exportFirewallPath=true
vbroker.se.iiop_tp.firewallPaths =Queen,King
vbroker.firewall-path.Queen=Atlantic,Pacific
vbroker.firewall-path.King=Indian
vbroker.firewall-path.Atlantic.type=TCP
vbroker.firewall-path.Atlantic.host=www.borland.com
vbroker.firewall-path.Atlantic.iiop_port=25000
vbroker.firewall-path.Atlantic.hiop_port=25003
vbroker.firewall-path.Atlantic.ssl_port=25004
vbroker.firewall-path.Pacific.type=PROXY
vbroker.firewall-path.Pacific.ior=http://www.mygk1domain.com/gatekeeper.ior
vbroker.firewall-path.Indian.type=PROXY
vbroker.firewall-path.Indian.ior=http://www.mygk1domain.com/gatekeeper.ior
In a client-side configuration, the GateKeeper IOR can be provided to the Client ORB. In such a scenario, the client makes all its operations using GateKeeper. In this case, the following properties are useful:
vbroker.orb.alwaysProxy=true
vbroker.orb.gatekeeper.ior=http://www.mydomain.com/gatekeeper.ior
In some cases, when the Smart Agent is not accessible by the client, GateKeeper is used to locate server objects. In such a scenario, it is recommended that you use the Location Service available through GateKeeper. In this case, the following property is used for GateKeeper:
vbroker.gatekeeper.locationService=true
Additionally, the following property is used on the client-side to locate objects:
vbroker.locator.ior=http://www.mydomain.com/gatekeeper.ior
Configuring GateKeeper with an HTTP proxy server
When an HTTP proxy server is running between the client and GateKeeper, GateKeeper needs to publish the HTTP proxy server's IP host/port address in its IOR. The technique described below can be used to achieve this goal. The following GateKeeper properties can be set which resemble a Network Address Translation configuration. In this case, the HTTP Proxy Server is acting as a NAT.
vbroker.se.exterior.proxyHost=142.186.142.21
vbroker.se.exterior.scm.ex-hiop.listener.proxyPort=32001
Note
Setting both of the above properties is not mandatory. In this scenario, GateKeeper appears to be behind a NAT device and, as such, all clients trying to communicate with GateKeeper using HTTP tunneling will always pass their requests through the HTTP Proxy Server.
Additional server engines in GateKeeper
There are three in-built server engines available in GateKeeper:
The iiop_tp server engine is used for administrative purposes only. The exterior and interior server engines are used for external and internal networks, respectively. When using TCP/IP networks, each server engine may be associated with a network IP host address, for example:
vbroker.se.exterior.host=142.186.142.21
vbroker.se.interior.host=142.186.182.30
vbroker.se.iiop_tp.host=192.73.8.25
This version of GateKeeper does not allow adding new server engines using the properties file.
Additional listeners or server connection managers in GateKeeper
GateKeeper can have more than one server connection manager (SCM) or listener for a given type of service. Usually, an SCM provides a specific type of service, such as IIOP, SSL, HIOP, HIOPS, and so forth. Each SCM is bound to a server engine, such as exterior or interior. To configure an SCM, you must assign a logical name (for example, myscm), and append this name to the following property:
vbroker.se.exterior.scms=ex-iiop,ex-hiop,myscm
Furthermore, the following properties must be added for each SCM (see Appendix A for more details):
vbroker.se.exterior.scm.myscm.manager.type=Socket
vbroker.se.exterior.scm.myscm.manager.connectionMax=0
vbroker.se.exterior.scm.myscm.manager.connectionMaxIdle=0
vbroker.se.exterior.scm.myscm.listener.type=IIOP
vbroker.se.exterior.scm.myscm.listener.port=683
vbroker.se.exterior.scm.myscm.listener.proxyPort=0
vbroker.se.exterior.scm.myscm.listener.giopVersion=1.2
vbroker.se.exterior.scm.myscm.dispatcher.type=ThreadPool
vbroker.se.exterior.scm.myscm.dispatcher.threadMax=100
vbroker.se.exterior.scm.myscm.dispatcher.threadMin=0
vbroker.se.exterior.scm.myscm.dispatcher.threadMaxIdle=300
GateKeeper stress/load metrics
Because GateKeeper is a Java based ORB service implementation, many Java tools can be used to obtain performance characteristics.
The VisiBroker Console provides certain real time performance characteristics about any ORB service (including GateKeeper). It can display information related to allocated memory, numbers of threads, connections, fragmentation, and so forth.
Deploying GateKeeper as a servlet
This section describes an example of deploying GateKeeper as a servlet into a Tomcat 5.0 web server. For earlier or later versions of Tomcat, some small modifications may be required.
This example makes use of the bank_agent example along with the supplied Client.properties, which among other things will force the client to connect to a server only via the gatekeeper servlet embedded in the web server. The bank_agent example is located in the following directory:
<install_dir>/examples/vbroker/basic/bank_agent
The additional files you will need to run the example in this scenario are:
web.xml - the deployment descriptor for gatekeeper to be deployed as a servlet.
Client.properties - the properties needed to set the bank_agent client to connect to the bank server via the GateKeeper embedded inside a web server as a servlet.
At the end of this section there are screen dumps of web.xml and Client.properties (see web.xml and Client.properties) which you can copy, paste, and save to designated files in specified directories.
Building the example
1
Download a free copy of Tomcat web server from http://jakarta.apache.org/tomcat/, and follow the instructions to install it. A properly functioning installation can be verified by launching a web browser for http://localhost:8080.
2
Copy, paste, and save web.xml to <Tomcat root install>/webapps/gatekeeper_servlet/WEB-INF/web.xml. Create sub-directories as needed.
3
<Tomcat root install>/webapps/gatekeeper_servlet/WEB-INF/web.xml
and change the following portion to correctly refer to your osagent Tomcat ports:
<init-param>
<param-name>vbroker.agent.port</param-name>
<param-value>YOUR OSAGENT PORT</param-value>
</init-param>
...
<init-param>
<param-name>
vbroker.se.exterior.scm.ex-hiop.listener.port
</param-name>
<param-value>
TOMCAT HTTP PORT. OUT OF TOMCAT BOX, THIS MUST BE 8080
</param-value>
</init-param>
4
<install_dir>/lib/
to
<Tomcat install root dir>/shared/lib
Putting the jars into the Tomcat shared/lib/ directory will make them available to all web applications deployed in the container. If this is not desired, consult the Tomcat documentation for the other lib directories.
lm.jar
sanctuary.jar
vbjorb.jar
sanct6.jar
vbjclientorb.jar
vbsec.jar
5
<install_dir>/examples/vbroker/basic/bank_agent
and open and edit the following settings.
vbroker.orb.gatekeeper.ior=http://<host>:<port>/gatekeeper_servlet/gatekeeper.ior
where <host> is the IP of machine on which Tomcat is running and <port> is the HTTP port to which Tomcat is listening. This must be the same number as the port in the web.xml above. For out-of the box Tomcat installations this must be set to 8080.
Running this example
1
2
3
4
5
Windows:
<Tomcat root install>/bin/startup.bat
UNIX:
<Tomcat root install>/bin/startup.sh
6
<install_dir>/examples/vbroker/basic/bank_agent
7
vbj Server
8
vbj -DORBpropStorage=Client.properties Client
web.xml
<?xml version=”1.0” encoding=”ISO-8859-1”?>
<!DOCTYPE web-app PUBLIC ”-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN” ”http://java.sun.com/dtd/web-app_2_3.dtd”>
<web-app>

<display-name>GateKeeper Servlet</display-name>

<description>GateKeeper as a servlet example</description>

<servlet>

<servlet-name>GateKeeperServlet</servlet-name>

<servlet-class>
com.inprise.vbroker.gatekeeper.servlet.Servlet
</servlet-class>

<load-on-startup />

<init-param>
<param-name>
vbroker.se.exterior.scm.ex-hiop.listener.path
</param-name>
<param-value>
/gatekeeper_servlet/servlet
</param-value>
</init-param>

<init-param>
<param-name>vbroker.agent.port</param-name>
<param-value>PUT YOUR OSAGENT PORT</param-value>
</init-param>

<!-- Some setups may not allow UDP broadcast to locate osagent
In that case, uncomment and set the following correctly
<init-param>
<param-name>vbroker.agent.address</param-name>
<param-value>
PUT IP OF THE MACHINE, ON WHICH OSAGENT IS RUNNING
</param-value>
</init-param>
-->

<init-param>
<param-name>vbroker.gatekeeper.referenceStore</param-name>
<param-value>
webapps/gatekeeper_servlet/gatekeeper.ior
</param-value>
</init-param>

<init-param>
<param-name>vbroker.se.exterior.scms</param-name>
<param-value>ex-iiop,ex-hiop</param-value>
</init-param>

<!-- If you want Visibroker log messages, uncomment this. Log messages will
   go to the specified file below, relative to Tomcat root install dir

<init-param>
<param-name>vbroker.orb.debug</param-name>
<param-value>true</param-value>
</init-param>

<init-param>
<param-name>vbroker.orb.logLevel</param-name>
<param-value>7</param-value>
</init-param>

<init-param>
<param-name>vbroker.orb.warn</param-name>
<param-value>2</param-value>
</init-param>

<init-param>
<param-name>vbroker.orb.logger.output</param-name>
<param-value>webapps/gatekeeper_servlet/log.txt</param-value>
</init-param>
-->

<init-param>
<param-name>
vbroker.se.exterior.scm.ex-iiop.listener.type
</param-name>
<param-value>Disabled-IIOP</param-value>
</init-param>

<init-param>
<param-name>
vbroker.se.exterior.scm.ex-hiop.listener.port
</param-name>
<param-value>8080</param-value>
</init-param>

<init-param>
<param-name>
vbroker.se.exterior.scm.ex-iiop.listener.port
</param-name>
<param-value>0</param-value>
</init-param>

</servlet>

<servlet-mapping>
<servlet-name>GateKeeperServlet</servlet-name>
<url-pattern>/servlet</url-pattern>
</servlet-mapping>

</web-app>
Client.properties
# The following line is only one (single) line
vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init,com.inprise.vbroker.HIOP.Init

vbroker.orb.alwaysTunnel=true
vbroker.orb.alwaysProxy=true

# The following line is only one (single) line
vbroker.orb.gatekeeper.ior=http://host:8080/gatekeeper_servlet/gatekeeper.ior

# Uncomment the following lines for debug messages
# vbroker.orb.debug=true
# vbroker.orb.warn=2
# vbroker.orb.logLevel=7