Gatekeeper Guide : AppendixGateKeeper properties

Appendix
GateKeeper properties
This appendix describes the properties that may be set on GateKeeper, with the exception of “Server's properties for firewall specifications”, which are properties set on the server.
Note
The following notations are used for the column “Default/Options” in the tables:
Options are in bold; gatekeeper.ior
General properties
The following table lists the common properties used by GateKeeper.
null - no name is defined <a user defined name>
gatekeeper.ior - in the current directory of GateKeeper. <Relative pathname> <Full pathname>
true (default) - enabled
false - disabled
-1 - cache is disabled
0 - cache size is unlimited
64 (default)
900 <an integer value>
false (default) - enabled
true - disabled
Exterior server engine
The following table lists the properties used by the exterior server engine on the client side or Internet side of GateKeeper. Most of the important properties, however, are defined in each Server Connection Manager (SCM) which are described in the following sections.
ex-iiop, ex-hiop (default) - ex-iiop and ex-hiop Server connection managers in use. It can also be a list of ex-iiop, ex-hiop, ex-ssl, and ex-hiops separated by commas.
null - the primary host is used; that is the IP address of the primary Network Interface Card (NIC). <a host address>
<empty> - No proxy host. <a fake host address>
Network Address Translation (NAT) devices hide the actual IP address and/or port number in the network by changing the IP address and/or in the IP packet. Set this value to the value defined by the NAT. When you have callback enabled and GateKeeper sits behind a NAT, the callback proxy host (vbroker.
gatekeeper.backcompat.callback.proxyHost
) should be set to equal this property. This is used when GateKeeper sits behind a NAT. You can also set this property using the VisiBroker Console.
ex-hiop server connection manager (SCM)
Java
The ex-hiop server connection manager is responsible for servicing HTTP requests on the exterior server engine. Both the listener and dispatcher properties are configured using the property with the vbroker.se.exterior.scm.ex-hiop prefix.
The following vbroker.se.exterior.scm.ex-hiop properties specify the behavior of the ex-hiop listener. The ex-hiop listener is an HIOP listener. The default port is 8088. The threading policy is set to ThreadSession.
Note
All the properties related to an SCM are defined with the following prefix: vbroker.se.<server engine name>.scm.<server connection manager name>.
Some SCMs may define additional properties, but some properties, especially the properties related to threads and connections, have the same property names for all SCMs.
8088
<a port number>
The proxyPort property is often used in conjunction with the server engine proxyHost property to mask the target port for this listener. If this property is set, the GateKeeper IOR file will contain the proxyPort value in the endpoint information for this listener. It is then the responsibility of the external NAT device to map the proxyPort to the listener's true port. The default is <empty> indicating the feature is disabled (the listener port will not be masked).
0 - incoming connections are unlimited
<an integer value>
0
<an integer value>
true (default) - enabled
false - disabled
true (default) - enabled
false - disabled
false (default) - disabled
true - enabled
false (default) - disabled
true - enabled
ex-iiop server connection manager (SCM)
The ex-iiop server connection manager is responsible for servicing IIOP requests on the exterior sever engine. The listener and dispatcher properties can be configured using properties with the vbroker.se.exterior.scm.ex-iiop prefix. The following vbroker.se.exterior.scm.ex-iiop properties specify the behavior of the ex-iiop listener. The ex-iiop listener is an IIOP listener.
Sets as a default listener port for GateKeeper's client-side IIOP listener. Port 683 is the recommended setting for a deployed application since it is an OMG standard for IIOP and is registered with IANA.
UNIX: On a UNIX platform, the default listener port number is in the range of 0 to 1024 which is reserved for privileged use. When running as a non-privileged user, the listener port can be set to a value greater than 1024 if desired.
<empty> - The proxy port feature is disabled.
This indicates the feature is disabled (the listener port will not be masked).
<a fake port number>
0 - incoming connections are unlimited
<an integer value>
false (default) - disabled
true - enabled
ex-hiops server connection manager (SCM)
Java
The ex-hiops server connection manager is responsible for servicing HTTPS requests on the exterior server engine. Both the listener and dispatcher properties are configured using the property with the vbroker.se.exterior.scm.ex-hiops prefix.
The following vbroker.se.exterior.scm.ex-hiops properties specify the behavior of the ex-hiops listener. The ex-hiops listener is an HIOPS listener. The default port is 8089. The threading policy must always be ThreadSession.
<empty>
<a fake port number>
The proxyPort property is often used in conjunction with the server engine proxyHost property to mask the target port for this listener. If this property is set, the GateKeeper IOR file will contain the proxyPort value in the end point information for this listener. It is then the responsibility of the external NAT device to map the proxyPort to the listener's true port. The default is <empty> indicating the feature is Disabled (the listener port will not be masked).
0 - the cached connections are unlimited
<an integer value>
0
<an integer value>
true (default) - enabled
false - disabled
true (default) - enabled
false - disabled
false (default) - disabled
true - enabled
false (default) - disabled
true - enabled
ex-ssl server connection manager (SCM)
The ex-ssl server connection manager is responsible for servicing SSL requests on the exterior sever engine. The listener and dispatcher properties can be configured using properties with the vbroker.se.exterior.scm.ex-ssl prefix.
The following vbroker.se.exterior.scm.ex-ssl properties specify the behavior of the ex-ssl listener. The ex-ssl listener is an ssl listener.
UNIX: On a UNIX platform, the default listener port number is in the range 0 to 1024 which is reserved for privileged use. When running as a non-privileged user, the listener port can be set to a value greater than 1024 if desired.
<empty> - The proxy port feature is disabled. This indicates the features is disabled (the listener port will not be masked).
<a fake port number>
0 - cached connections are unlimited.
<an integer value>
0
<an integer value>
false (default) - disabled
true - enabled
Interior server engine
The following table lists the properties used by the interior server engine on the server-side or Intranet side of GateKeeper.
You may need to set some of the properties in the interior server engine in special cases, such as when GateKeeper runs on a dual-homed machine or if there is a Network Address Translation (NAT) between GateKeeper and the server.
in-iiop (default), in-hiop, in-ssl, in-hiops
<Combination of the above separated by commas.>
Null - the primary host is used; that is the IP address of the primary Network Interface Card (NIC).
<a host address>
<empty> - The proxy port feature is disabled.
<a fake host address>
in-iiop server connection manager (SCM)
The in-iiop server manager is responsible for servicing IIOP requests on the interior server engine. The listener and dispatcher can be configured using properties with the vbroker.se.interior.scm.in-iiop prefix.
The following vbroker.se.interior.scm.in-iiop properties specify the behavior of the in-iiop server connection manager.
0 - pick a random number
<a port number>
<empty> - The proxy port feature is disabled.
<a fake port number>
0 - cached connections are unlimited.
<an integer value>
false (default) - disabled
true - enabled
in-ssl server connection manager (SCM)
The in-ssl server manager is responsible for servicing SSL requests on the interior server engine. The listener and dispatcher can be configured using properties with the vbroker.se.interior.scm.in-ssl prefix.
The vbroker.se.interior.scm.in-ssl properties listed below specify the behavior of the in-ssl server connection manager.
0 - pick a random number
<a port number>
<empty> - The proxy port feature is disabled.
<a fake port number>
0 - incoming connections are unlimited.
<an integer value>
false (default) - disabled
true - enabled
Administration
Java: The following table lists the administration properties. Note that the default listener port number is 9091.
null - use host address from the system.
<Host address>
<empty> - use host address from the system.
<Proxy host address>
iiop_tp, hiop_ts
<empty>
<a port number>
<empty>
<a port number>
9091
<a port number>
<empty> - The proxy port feature is disabled
<a fake port number>
true (default) - enabled
false - disabled
true (default) - enabled
false - disabled
false (default) - disabled
true - enabled
false (default) - disabled
true - enabled
Access control
The following table lists the properties used to set security control in GateKeeper.
null (default) - no default action
deny - refused entry
grant - permission granted
null - no actions specified. See description for additional options.
<deny | grant>
[operation=”<
operation name>”
[signer by=”<signer's company name>”]
[server host=”<hostname>”]
[client host=”<hostname>”]
[server ip=aa.bb.cc.dd | <sub-mask>]
[client ip=aa.bb.cc.dd | <sub-mask>]
[object type=”<object type>”] ]

<deny | grant>
defines the action related to the individual rule.
operation=”<operation name>” defines the related operation name based on the IDL.
signer by=”<signer's company name>” defines the signer's company name.
server host=”<hostname>” specifies the server hostname.
client host=”<hostname>” specifies the client hostname.
server ip=”<aa.bb.cc.dd>” specifies the IP address of the machine that the server resides on.
client ip=”<aa.bb.cc.dd>” defines the IP address of the machine that the client resides on.
object type=”<object type>” defines the object type.
vbroker.gatekeeper.security.accessControllers=default

vbroker.gatekeeper.security.acl.default.rules=rule1,rule2,rule3
vbroker.gatekeeper.security.acl.default.rule1=
grant
[operation=\”*”\
[server host=\”borland”\]]

vbroker.gatekeeper.security.acl.default.rule2=deny
[operation=\”*”\
[client ip=192.168.100.40 | 255.255.255.0]]

vbroker.gatekeeper.security.acl.default.rule3=deny
[operation=\”*”\
[server host=\”inprise”\]
[client ip=192.168.100.88 | 255.255.255.0]]
null - no rules specified. See description.
where rule1, rule2, rule3 are names defined by the user.
VisiBroker 3.x style callback
The following table lists the properties that can be set in VisiBroker 5.x and later to use the VisiBroker 3.x style callback.
false (default) - disabled
true - enabled
false (default) - disabled
true - enabled
<empty> - the value is set to the primary host IP address and that is the IP address of the primary NIC.
<a host address>
This property is often used in conjunction with the server engine proxyPort property to mask the target port for this listener. If this property is set, the callback IOR will contain the proxyHost value in the end point information for this listener. It is then the responsibility of the Network Address Translation (NAT) device to map the proxyHost to the listener's true port. The default is <empty> indicating that the feature is disabled (the listener port will not be masked in the callback IOR).
0-a port picked at random
<port number>
0 - a port number is picked at random.
<a port number>
<empty> - no proxy port is used.
<a fake port number>
The proxyPort property is often used in conjunction with the server engine proxyHost property to mask the target port for this listener. If this property is set, the callback IOR will contain the proxyPort value in the end point information for this listener. It is then the responsibility of the Network Address Translation (NAT) device to map the proxyPort to the listener's true port. The default is <empty> indicating that the feature is disabled (the listener port will not be masked in the callback IOR).
Performance and load balancing
The following table lists the performance and load balancing properties to distribute and monitor the load between client and server.
0 - will not try to close any of the old active or cached connections.
<an integer value>
4096
<a number which is the power of 2>
6000
<an integer value>
<empty> - no slaves GateKeeper
<a list of slaves> - see description.
Note: If you set this property, you must load the appropriate library. See the description of vbroker.orb.dynamicLibs in Miscellaneous ORB properties.
<empty>
<Specific Slave IOR> - see description.
Specifies the IOR or a URL pointing to specific Slave GateKeeper to be clustered for the purpose of Load Balancing by this Master GateKeeper. Note that this property is used in Master GateKeeper property only. For example: vbroker.gatekeeper.load.slave.abc=http://host1:9091/GateKeeper.ior
vbroker.gatekeeper.load.slave.xyz=http://host2:9091/GateKeeper.ior
.
Note: If you set this property, you must load the appropriate library. See the description of vbroker.orb.dynamicLibs in Miscellaneous ORB properties.
<empty>
<master>
Support for bidirectional communications
The following table lists the properties that support bidirectional communications. These properties are evaluated only once, when the SCMs are created. In all cases, the exportBiDir and importBiDir properties on the SCMs are given priority over the enableBiDir property. In other words, if both properties are set to conflicting values, the SCM-specific properties will take effect. This allows you to set the enableBiDir property globally, and more importantly, turn off bidirectionality in individual SCMs.
You can selectively make bidirectional connections. If the client defines vbroker.orb.enableBiDir=client, and the server defines vbroker.orb.enableBiDir=server, the value of vbroker.orb.enableBiDir in GateKeeper determines the state of the connection.
Note: Just as you can selectively enable bidirectional communication on a per-SCM basis, you can also selectively enable bidirectional communication on GateKeeper. For example, if you set the vbroker.se.exterior.scm.ex--iiop.manager.importBiDir property to true, GateKeeper will accept bidirectional connections from the client. Setting the vbroker.se.exterior.scm.ex--iiop.manager.
exportBiDir
property to true causes GateKeeper to request bidirectional connections with the server.
Support for pass-through connections
Note
The vbroker.gatekeeper.enablePassthru property is the only property that supports pass-through connections.
false (default) - disabled
true - enabled
16384
<an integer value>
300000 milliseconds (5 minutes)
<an integer value>
1024
<a port number>
Used together with vbroker.gatekeeper.
passthru.inPortMax
. It specifies the start of a range of interior port for pass-through incoming connections.
65535
<a port number>
Used together with vbroker.gatekeeper.
passthru.inPortMin
. It specifies the end of a range of ports for pass-through in-coming connections.
0 - no logging
<an integer value>
0
<a port number>
Used together with vbroker.gatekeeper.
passthru.outPortMax
. It specifies the start of a range of exterior port for pass-through outgoing connections.
65535
<a port number>
Used together with vbroker.gatekeeper.
passthru.outPortMin
. It specifies the end of a range of exterior port for pass-through outgoing connections.
2000
<an integer value>
Security services (SSL)
The following table lists the properties used in the Security Services.
Note
If you set this property then you load the appropriate library. See the description of vbroker.orb.dynamicLibs in Miscellaneous ORB properties.
false (default) - disabled
true - enabled
Refer to the VisiBroker Security Guide for more details.
Refer to the VisiBroker Security Guide for more details.
Refer to the VisiBroker Security Guide for more details.
Refer to the VisiBroker Security Guide for more details.
Location services (Smart Agent)
The following table lists the Smart Agent (OSAgent) properties used in the Location Service to locate server objects.
See Using the Smart Agent in either the VisiBroker for Java Developer's Guide or the VisiBroker for C++ Developer's Guide for more details of these properties.
null - see description.
Specifies the IP address or host name of the host running the Smart Agent (OSAgent). The default value, null, installs VisiBroker applications to use the value from the OSAGENT_ADDR environment variable. If the OSAGENT_ADDR variable is not set, it is assumed that the Smart Agent is running on the local host or will be located by a broadcast message.
true (default)
false
When set to true, allows a VisiBroker application to failover to another Smart Agent.
true (default)
false
When set to true, allows VisiBroker applications to cache object references. Setting this property to true improves performance when locating servers, but disables Smart Agent round-robin activity.
Backward compatibility with VisiBroker 4.x and below
From VisiBroker version 5.x onwards, GateKeeper by default is not compatible with programs developed with VisiBroker 4.x and below. To make GateKeeper run properly with programs developed with VisiBroker 4.x and below, set the following property to true.
Note
Earlier versions of GateKeeper are by default compatible with older programs developed with Visibroker 4.x and below. From GateKeeper 5.x, however, you must explicitly set this property.
true (default)
false
Specifies whether GateKeeper is compatible with older VisiBroker versions. Setting the property to false makes GateKeeper compatible with programs developed with VisiBroker 4.5.x onwards. Setting this property to true makes GateKeeper compatible with versions earlier than VisiBroker 4.5.x as well. (See “Appendix GateKeeper deployment scenarios” for more information.)
Note: This value is set to true by default in GateKeeper. This value, however, is false by default on the client and server.
Server's properties for firewall specifications
These properties should only be set in the property file for the server. If you set any of these properties then you load the appropriate library. See the description of vbroker.orb.dynamicLibs (for Java) and vbroker.orb.enableFirewall (for C++) in Miscellaneous ORB properties.
The following properties specify the communication paths from the client to the server. See “Specifying communication paths to the server” for examples of its usage.
<empty>
<List of paths>
<empty>
<List of components>
Specifies the list of components in the firewall path <pathname>. For example, vbroker.
firewall-path.x=a,b vbroker.firewall-path.y=c
<empty>
PROXY TCP
Specifies the type of the components. For example: vbroker.firewall.a.type = PROXY vbroker.firewall.b.type = TCP
<empty>
<Filename of ior file>
<URL of the ior file>
IOR:<GateKeeper's stringified ior>
<empty>
<fake host name>
Specifying fake host of the server. This is specified together with vbroker.firewall.<component>.types=TCP and the component is a TCP Firewall with NAT.
<empty>
<fake IIOP Port>
Specifies a fake IIOP port for the server. This is specified together with vbroker.firewall.<component>.type=TCP and the component is a TCP Firewall with NAT.
<empty>
<fake SSL Port>
Specifies a fake SSL port for the server. This is specified together with vbroker.firewall.<component>.type=TCP and the component is a TCP Firewall with NAT.
<empty>
<fake HIOP Port>
Specifies a fake HIOP port for the server. This is specified together with vbroker.firewall.<component>.type=TCP and the component is a TCP Firewall with NAT.
Miscellaneous ORB properties
These properties are common ORB objects and are directly and indirectly related to GateKeeper. They are not necessarily set in the GateKeeper property file, so please read each description carefully.
<empty>
<ior filename>
false (default) - disable
true - enabled
Specifies whether the client must always connect to the server via GateKeeper. This property can be set in the client or GateKeeper. If set to true in the client, the client will always connect to the server via GateKeeper. If set to true in GateKeeper, it will connect to the server via another GateKeeper.
<empty>
<ior filename>
Note: GateKeeper provides limited location services. It cannot forward location requests to another GateKeeper. This is in contrast to the Smart Agent which is able to forward requests to another available Smart Agent.
false (default) - disabled
true - enabled
Specifies whether the client must always make HTTP tunnel (IIOP wrapper) connections to the server. When set to true, specifies that the client always make connections to the server using HTTP tunnel (IIOP wrapper). This property can be set in the client or GateKeeper.
<empty>
<a list of libraries>
false (default) - disabled
true - enabled
Setting this property to true at the C++ client and C++ server loads the required firewall library to enable the firewall feature with Gatekeeper.
false (default) - disabled
true - enabled
If this property is set to true, and if the IOR has both IIOP and TCP type firewall components, then if any one of the end points fails, fail-over can occur.
Setting vbroker.orb.alwaysProxy=true or a programmatically configured firewall proxy takes precedence.