How You Can Configure the OpenROAD Java Gatekeeper3
The gatekeeper3 web server application contains support for the following:
• OpenROAD JSON RPC servlet
• OpenROAD gatekeeper servlet (like the gatekeeper2 servlet)
The gatekeeper3 provides compiled Java files in Java JAR files that are ready to use.
The location of the installed files for this gatekeeper are listed in OpenROAD Server Java Gatekeeper3 Components. They include:
index.html
To test OpenROAD Server access in Tomcat, copy index.html to the webapps subdirectory, for example, %CATALINA_HOME%\webapps\openroad.
If you open the page in a web browser without the sub-context for the gatekeeper or any JSON-RPC application configured (ComTest, JsonRpcServerTest, and so on)—for example, using http://localhost:8080/openroad—a simple web page is opened:
This page lets you check whether these OpenROAD servlets are running: Gatekeeper and JsonRpcServerTest. Clicking the Gatekeeper link displays results like this:
Clicking the JsonRpcServerTest link displays results like this:
Clicking the Test button performs a test using the JsonRpcServerTest application. It sends a JSON-RPC request over HTTP POST and displays the results, like this:
openroad.jar
Contains common support for the OpenROAD Java Native Interface (JNI). This file can be shared between several different applications.
orgatekeeper3.jar
Contains support for the OpenROAD JSON RPC servlet and the OpenROAD gatekeeper servlet.
readme.txt
Points to this documentation.
web.xml
Used with the orgatekeeper3.jar file. Provides support for the following URLs:
URL Name | Description |
|---|---|
http://localhost:8080/openroad/gatekeeper | OpenROAD gatekeeper servlet |
http://localhost:8080/openroad/jsonrpc?app=jsonrpcservertest | OpenROAD JSON RPC servlet: jsonrpcsservertest |
http://localhost:8080/openroad/jsonrpc?app=comtest | OpenROAD JSON RPC servlet: comtest |
The OpenROAD gatekeeper servlet provides a proprietary interface to the OpenROAD Server through the 4GL, .NET, and Java clients. You can access all OpenROAD Server applications using this URL.
The OpenROAD JSON RPC Server requires a unique URL to access each OpenROAD application that is enabled for JSON RPC access.
The environment variable II_W4GL_JSON_CONFIG specifies the full location for the JSON-RPC configuration directory used by the OpenROAD Server.
The OpenROAD JSON RPC servlet is dependent on the Java Server API. The minimum version of this API is 3.1 (for more information, see http://tomcat.apache.org/whichversion.html).
Prepare for Tomcat
To prepare your OpenROAD server to work with Tomcat, follow the appropriate procedure for your platform. For more information about installing Tomcat, see Installing Tomcat.
For all platforms: Set the CATALINA_HOME environment variable. It should point to the directory containing the Tomcat installation.
To prepare a Windows server for Tomcat
1. Create a new subdirectory in %CATALINA_HOME%\webapps (use “webapps-javaee” instead of “webapps” for Tomcat 10). For example:
mkdir "%CATALINA_HOME%\webapps\openroad"
mkdir "%CATALINA_HOME%\webapps-javaee\openroad"
2. Copy the WEB-INF subdirectory from %II_SYSTEM%\ingres\orjava\Gatekeeper3 into the subdirectory created in Step 1.
3. If you have not done this yet, copy the %II_SYSTEM%\ingres\orjava\openroad.jar file into %CATALINA_HOME%\lib.
4. Launch the Apache Tomcat 9.0 properties executable using this command from an administrative command prompt:
"C:\Program Files\Apache Software Foundation\Tomcat 9.0\bin\Tomcat9w.exe"
5. Click the Java tab and navigate to the Java Options entry field. Enter this as the last line in the field:
-Djava.library.path=%II_SYSTEM%\ingres\bin
Replace %II_SYSTEM% in the string above with the actual value of the II_SYSTEM variable.
To prepare a Linux or UNIX server for Tomcat
1. Create a new subdirectory in $CATALINA_HOME/webapps (use “webapps-javaee” instead of “webapps” for Tomcat 10). For example:
mkdir $CATALINA_HOME/webapps/openroad
2. Copy the WEB-INF subdirectory from $II_SYSTEM/ingres/orjava/Gatekeeper3 into the subdirectory created in Step 1.
3. If you have not done this yet, copy the $II_SYSTEM/ingres/orjava/openroad.jar file into $CATALINA_HOME/lib.
You now may configure Tomcat (Authentication and Servlet Options—see How You Configure Tomcat) and restart it.
Test the servlets
To test the servlets, use these commands:
comtestrso http://localhost:8080/openroad/gatekeeper http
comtestrso http://localhost:8080/openroad/comtest http-jsonrpc
How You Configure Tomcat
Authentication:
The web.xml configuration file is configured to use BASIC web server authentication (with username and password) with a role called "orspo_users". A default Tomcat installation uses the $CATALINA_HOME/conf/tomcat_users.xml file for authentication information.
You must add the orspo_users role and corresponding user entries under the <tomcat-users> tag in the tomcat_users.xml file, for example:
<tomcat-users>
...
<role rolename="orspo_users"/>
<user username="testuser" password="xyz" roles="orspo_users"/>
</tomcat-users>
OpenROAD Gatekeeper Servlet Options:
You may configure the OpenROAD gatekeeper servlet with the following InitParameters in the web.xml file:
OpenROAD_ServerApp
Defines the name of the OpenROAD Server application that the gatekeeper connects to. If this parameter is missing or set to *, it allows the application name to be provided by the "image" parameter of the Initiate request. We recommend that you create separate webapps for different OpenROAD applications.
permittedSCPs
Limits the access to permitted SCPs. If this parameter is missing or set to *, it allows access to all SCPs. SCP names are delimited by whitespaces (space, tab, newline, carriage-return, form-feed).
logcalls
When set to 1, logs requests to the OpenROAD Gatekeeper in the file $CATALINA_HOME/logs/localhost_log.yyyy-mm-dd.txt. This parameter is used for testing purposes.
url-pattern
In the gatekeeper2, this defined a value of "*". This allowed any value appended after the base URL to be mapped to the OpenROAD gatekeeper. The value in the gatekeeper3 is defined as "gatekeeper". The expected URL takes the following form:
HOSTNAME/WEBAPPNAME/gatekeeper
If the HOSTNAME is "localhost:8080" and the WEBAPPNAME is "openroad", the URL is as follows:
localhost:8080/openroad/gatekeeper
This differs from the gatekeeper2 URL:
localhost:8080/openroad
This change allows the OpenROAD gatekeeper and the OpenROAD JSON RPC servlet to be supported by a common web.xml configuration file.
OpenROAD JSON RPC Servlet Options:
logcalls
When set to 1, logs requests to the OpenROAD gatekeeper in the file $CATALINA_HOME/logs/localhost_log.yyyy-mm-dd.txt. This parameter is used for testing purposes.
private_session_idletimeout
Specifies the inactivity timeout (in seconds) for the HTTP sessions used for private RemoteServer connections (default is 3600).
rso_idletimeout
Specifies the timeout (in seconds) for shared RemoteServer connections (default is 3600).
url-pattern
The following is the URL pattern needed to invoke the OpenROAD JSON RPC servlet. The expected URL takes the following form:
HOSTNAME/WEBAPPNAME/SERVLETMAPPING?app=JSONRPCAPPLICATION
If the HOSTNAME is "localhost:8080", the WEBAPPNAME is "openroad", the SERVLETMAPPING is "jsonrpc", and the JSONRPCAPPLICATION is "jsonrpcservertest", the URL is:
localhost:8080/openroad/jsonrpc?app=jsonrpcservertest
This value is used internally and does not need to be installed. It is provided for diagnostic support and is not used during the normal operation of the JSON RPC Server.
Frequently Asked Questions
How do I provide the username and password on initiate?
User credentials can be provided with the flags parameter of the RemoteServer.Initiate() method. For example, for the previous case:
rso.Initiate(..., flags=':testuser:xyz::');
If the username and password are not provided, the user will be prompted to provide login credentials (only on the first initiate).
How is security applied?
Authorization is performed using the web server. An authorized user may call any SCP provided by the application(s) configured by the OpenROAD_ServerApp config parameter. Additional security should be provided by using SSL encryption—see http://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html.
Customized authentication or authorization can be accomplished through advanced web server configuration or customizing the Java source of the gatekeeper (this requires a Java SDK).
Can the authorization be switched off?
Web server authentication can be switched off by removing the <security-constraint>, <login-config>, and <security-role> tags from the web.xml file. This can be useful for testing or if you use applications in a trusted environment.
What is the URL of the gatekeeper?
The URL is the address of the web server, extended by the name of the directory for the web application, for example:
http://myhost:8080/openroad/gatekeeper
Or
https://myhost:8443/openroad/gatekeeper
Appending the name of the servlet is not required, as this is already configured in the web.xml file.
Last modified date: 12/20/2023