Ping URI Test
To initiate a system sanity check that tests the policy engine container and the connection to the database, use a monitoring tool or the Load Balancer to access the ping URI of each gateway or each node in a Gateway cluster. The ping URI response returns as a HTML page.
To initiate a system sanity check that tests the policy engine container and the connection to the database, use a monitoring tool or the Load Balancer to access the ping URI of each
Layer7 API Gatewayor each node in a Gateway cluster. The ping URI response returns as a HTML page.
The Ping URI Test is not affected by the shutdown threshold specified by the
audit.archiverShutdownThresholdAudit Archiver Cluster Properties. It only validates the connection to the Gateway and its database. A successful ping does not necessarily indicate normal message processing. And message processing that is halted by an overly-full database does not affect the Ping URI Test results.
WARNING:Do not run a Ping URI Test to do a node health check during a load balancer availability check. Doing so impacts the performance of the cluster significantly. For an alternative, see "Load Balancer Health Check" in Configuring the Load Balancer.
The following factors determine the outcome of a call to the ping URI:
- The setting for thepingServlet.modecluster property
- Whether the ping URI request was submitted through standard HTTP or encrypted HTTP using SSL (see "Syntax" below)
- Whether credentials were included in the ping URI request (see "Syntax" below)
(1) To catch potential network issues early and maximize uptime, configure a monitoring schedule of once a minute or more for each Gateway Ping URI in the implementation. Do not ping each Gateway node using Ping URI more often than once every five seconds, as doing so may adversely affect the performance of the system. (2) For the Ping service to work successfully in a cluster over SSL, ensure that nodes in a clustered environment have been configured to trust each other. For more information, see Manage Certificates.
The syntax for submitting a ping URI test through standard HTTP:
The syntax for submitting a ping URI test via encrypted HTTP using SSL:
- (without credentials)https://<ssghost>:8443/ssg/ping
- (with credentials)https://<user>:<password>@<ssghost>:8443/ssg/ping
In Internet Explorer, embedding the username and password in the URI is not supported after installing
MS04-004 Cumulative Security Update for Internet Explorer(832894). For more information, please see http://support.microsoft.com/kb/834489.
- <ssghost>is the name of the machine hosting the Gateway, in the format:hostname.domain.com
- <user>is the user ID for logging into the Gateway
- <password>is the password for the user ID
If a user has a client certificate registered on the Gateway, then the user is required to use the client certificate when performing a ping URI test through SSL.
Ping URI Test Results
The following table summarizes the ping URI test results based on each
pingServlet.modecluster property setting.
All pings are discarded, regardless of the protocol used.
For pings submitted via SSL with credentials, the following is returned: Gateway state, full cluster status, and build number.
For pings submitted via SSL without credentials, a "401 Unauthorized" is returned.
All other ping attempts are discarded.
Note:In REQUIRE_CREDS mode, users must belong to a role with read access to cluster node information. See "Roles and Permissions" below for more information.
For pings submitted via standard HTTP, the Gateway state is returned.
For pings submitted via SSL, the following is returned: Gateway state, full cluster status, and build number.
Note that credentials are not required for the OPEN setting.
Returns a minimal status message to the client, without providing any node system information.
Roles and Permissions
pingServlet.modecluster property is set to REQUIRE_CREDS, the user must belong to a role with read permissions for cluster node information in order for the ping to be acknowledged. The predefined roles that include this permission are:
- Manage Cluster Status
- View Audit Records and Logs
- View Service Metrics
If the correct permission is not present, ping attempts from that user are discarded.
For more information about roles and permissions, see:
Full Cluster Status
When the full cluster status is displayed (see "Ping URI Test Results" above), a table similar to the following is displayed in the HTML results page:
1 day 3 hours 2 mins
2 days 2 hours 39 mins
- Node:Name of the Gateway node
- Uptime:Time duration since Gateway process startup on this node, rounded to the nearest minute. If a node has failed, the uptime shows a question mark ("?") instead.
- Status:Each node in the cluster updates the timestamp in the database periodically. If a node is down, the timestamp begins to fall behind compared to the current time. The status indicators are:
- OK= Timestamp is no older than 30 seconds
- Warning= Timestamp is older than 30 seconds but younger than 1 hour
- FAIL= Timestamp is older than 1 hour; when a node has failed, the uptime cannot be determined
- System Info:Returns extended system information in a separate web page. You can use this information to help troubleshoot problems. This information also helps CA Technical Support diagnose issues if you require further assistance.You need the rolesAdministratororOperatorto view extended system information
If the nodes are active but the database has failed, the full cluster status is not displayed. Instead, one of the following messages is returned:
- FAILURE: Cannot connect to database from <machinename.domain.com>
To verify that the Gateway is working correctly, configure a monitoring application to search for the string "OK" or the protocol status "200" in the HTML results page. If not found, then the monitoring system should proceed to raise an alert.