How to Check If a Virtual DataPort Server Is Alive¶

When you connect to Denodo through a load balancer or an application that creates a pool of connections to Virtual DataPort, the load balancer or the application need a way to check that a connection is still valid. The following sections explain different alternatives to check the health of a connection.

Using the Ping Script¶

The script ping checks that a Virtual DataPort server is “alive”. It is located in the directory <DENODO_HOME>/bin.

Syntax of the ping script¶

ping [ -t timeout ] [ -r ] [ -q <query> -l <login> [ -p <password> | -cf <configuration file> ] ] [ -v ]
     <host>[:<port>][/<database name>

Parameters of the ping script¶
Parameter	Description
-t	Optional. Time to wait for a response, in milliseconds. If after this period the script does not receive a response, it returns an error.
-r	Optional. Checks when the server is ready for processing queries and not in single user/promotion mode (optional, ignored when using -q).
-q <query>	Optional. If present, the script, besides checking if the Virtual DataPort server is up, it executes a query. If you indicate this parameter, you also have to pass the login and password of the user. In many operating systems, you have to surround the query with double quotes so the query is considered a single parameter.
-l	Mandatory when using `-q`. Login.
-p	Password. Incompatible with `-cf`. You can provide the password encrypted by prefixing it with `encrypted:` (use the script `encrypt_password` to encrypt the password). E.g. `-p "encrypted:UjOsIu8972jviqGpcLP3Mg=="` If you provide the login (`-l`) but not the password (`-p`) nor the configuration file (`-cf`), the script will prompt for your password. If you are going to invoke this from another script of application, we recommend encrypting the password; to avoid putting in plain text.
-cf <file>	Incompatible with `-p`. File with one line that contains this: `password=<password>` or this: `password=encrypted:<encrypted_password>` (Use the script `encrypt_password` to encrypt the password)
-v	Optional. If present, the script displays the status the time taken to receive a response from the Server. Otherwise, it only displays error messages.
<host>	Host of Virtual DataPort.
<port>	Optional. If not present, the script sends the request to the default Virtual DataPort port: 9999.
<database>	Mandatory when using `-q`. The database that the query will be executed.

This script returns 1 if there is any error (e.g. the server cannot be reached or the query fails or the timeout is reached…). If the script finishes correctly, it returns 0.

Examples

Example 1

For Windows:

<DENODO_HOME>\bin\ping.bat -v -t 30000 -q "SELECT 1" -l monitor_user -p "encrypted:UjOsIu8972jviqGpcLP3Mg==" //denodo-dv1.acme.com/admin

For Linux:

<DENODO_HOME>/bin/ping.sh -v -t 30000 -q "SELECT 1" -l monitor_user -p "encrypted:UjOsIu8972jviqGpcLP3Mg==" //denodo-dv1.acme.com/admin

This sends a ping request to “denodo-dv1.acme.com”:

If the server responds, it executes the query “SELECT 1” on the database “admin”. Note that the query (-q parameter) needs to be surrounded by double quotes so the query is considered a single parameter.
If connecting to Virtual DataPort and running the query takes more than 30 seconds, the script fails.
Note that the password (parameter -p) starts with encrypted:. That is because what follows is the password encrypted.

To encrypt the password of a user account, execute this:

On Windows:

<DENODO_HOME>\bin\encrypt_password.bat

On Linux:

<DENODO_HOME>/bin/encrypt_password.sh

Enter your password and press Enter; the script will return your password encrypted. You can also pass your password as a parameter of this script.

Example 2

ping -t 30000 -v //denodo-dv1.acme.com:19999

Sends a ping request to a Virtual DataPort that listens on the port 19999, with a timeout of 30 seconds. Unlike in the previous example, this one does not execute any query. That is why you do not need to specify the user and password.

Alternatives to the Ping Script¶

In some environments, the load balancer cannot execute a ping query or use the standard ping script to verify service availability. In these cases, an alternative strategy is required to determine whether the service is up and responsive.

Unauthenticated health-check endpoint for RESTful Web Service¶

To address this scenario, Denodo provides a dedicated unauthenticated health‑check (ping) endpoint within the Virtual DataPort RESTful Web Service, intended for use by infrastructure components such as load balancers. When enabled, the load balancer can issue an HTTP GET request to this endpoint and rely on the response code as a health signal: the endpoint returns 200 OK when availability is successfully validated (the ping to Virtual DataPort succeeds) and 503 Service Unavailable when the validation fails, offering a simple and reliable mechanism even when authenticated REST calls are not suitable.

Endpoint URL¶

Two new properties control this feature:

To enable endpoint you must execute this:

SET 'com.denodo.restfulws.pingEndpoint.enabled' = 'true';

The default endpoint name is Ping, and, once enabled, the endpoint is available at:

http://<host>:<port>/denodo-restfulws/Ping

The endpoint name is configurable, you can set the custom endpoint name by executing:

SET 'com.denodo.restfulws.pingEndpointName' = 'customPingEndPoint';

With this configuration the endpoint will be available at:

http://<host>:<port>/denodo-restfulws/customPingEndPoint

Note

Name collision with databases. Because the ping endpoint is published under /denodo-restfulws/, it can override a database with the same name. For example, if the endpoint name is Ping and there is also a database called Ping. To avoid collisions, set com.denodo.restfulws.pingEndpointName to a different value (e.g., customPing, restHealth, …).

Note

After setting or changing these properties, the Virtual DataPort server must be restarted for changes to take effect.

Behavior (API contract)¶

HTTP method: GET
Authentication: Not required
Responses:
- 200 OK when the endpoint can successfully ping Virtual DataPort (service is healthy).
- 503 Service Unavailable when the ping/validation fails (service is unhealthy).

Load Balancer Integration¶

Configure the load balancer health probe to send GET requests to:

/denodo-restfulws/<pingEndpointName>

Suggested health criteria:

Healthy if HTTP status = 200
Unhealthy if HTTP status = 503 (or timeouts)

This approach provides a direct indication of RESTful Web Service health without relying on credentials, views, or query execution.

Security Considerations¶

Since the endpoint is unauthenticated, it should remain minimal and non-informative:

Do not expose data, metadata, or detailed error information.
If possible, restrict network access (Load balancer IP allowlist, segmentation, or Firewall rules).
Keep the feature disabled by default and enable it only where required.

USER MANUALS