License Reporter Tool

Overview

For environments with strict security requirements or "air-gapped" configurations where a direct outbound connection to the licensing service is restricted, Capacity Private Cloud provides a specialized synchronization utility.

This tool facilitates the manual exchange of utilization data between the local cluster and the Capacity licensing endpoint (https://licensing.lumenvox.com). It acts as a secure intermediary, allowing administrators to inspect all JSON payloads for security auditing before they are transmitted or ingested.

Connectivity & Access

If your security policy prevents the cluster from communicating over port 443, please contact Capacity Support to obtain the latest version of this utility.

Command Line Parameters

Run the tool without any parameters to see usage information. The following parameters are needed to run correctly:

  • reportingApiUri
  • deploymentId
  • operatorId
  • authString
  • responseJson
  • operation

Operation is an important parameter, and can be one of the following 3 values:

operation: report

Requires the following additional parameters:

  • deploymentId
  • operatorId

This can be called as follows:

license-reporter-tool -operation "report" -deploymentId "XXXXXX-086f-42f0-a728-d95f39dc2229" -operatorId "XXXXXXX-bddb-4979-8284-531641b16eda" -enableTls=true -reportingApiUri=reporting-api.XXXXXXXX.com:443

and give the following output:

License Usage Report: {"ETRAN_ENUS":{"usage_count":1,"usage_ms":2800},     "ETRAN_ENUS_50":{"usage_count":1,"usage_ms":2800},"INTERACTION_USAGE":{"usage_count":4,    "usage_ms":610644},"SESSION_USAGE":{"usage_count":4,"usage_ms":615524},    "TRAN_ENUS":{"usage_count":3,"usage_ms":187618},"VAD":{"usage_count":2,"usage_ms":66900}}

Note: use valid deploymentId and operatorId values when making these calls.

operation: cluster-pull

Requires the following additional parameters:

  • deploymentId
  • operatorId
  • authString - this should be the one assigned to the customer by LumenVox

This can be called as follows:

license-reporter-tool -operation "cluster-pull" -deploymentId "XXXXXXX-086f-42f0-a728-d95f39dc2229" -operatorId "XXXXXXX-bddb-4979-8284-531641b16eda" -authString "XXXXXXXX" -enableTls=true -reportingApiUri=reporting-api.XXXXXXXX.com:443

Note: use correct deploymentId and authString when calling this.

and returns:

## performing LicenseStatusReportPull to get license report to send to cloud from cluster... Use the following curl command (or similar) to report to LumenVox cloud... 
curl https://licensing.lumenvox.com -H "x-auth-string: XXXXXXXXX" \    -H "Content-Type: application/json" \    -d "{\"cluster_guid\":\"XXXXXXXXXX-904e-4ef4-af51-390c5e1b7a15\",     \"instance_uuid\":\"91347bef-96fa-4b2d-8e30-4c2aa77f437b\",     \"status_id\":\"XXXXXXX-fc38-43a5-a10c-0e7dfd45da47\",     \"instance_created\":\"2023-08-29T17:44:27.334937-07:00\",\"installation_type\":\"Undefined\",    \"report_timestamp\":\"1693954219\",\"images\":null,    \"deployments\":[{\"license_guid\":\"XXXXXXXX-086f-42f0-a728-d95f39dc2229\",    \"bio_engine_usage\":null,\"speech_usage\":{\"session_ms\":615524,\"session_audio_ms\":192877,    \"license_usage\":{\"ETRAN_ENUS\":{\"usage_count\":1,\"usage_ms\":2800},    \"ETRAN_ENUS_50\":{\"usage_count\":1,\"usage_ms\":2800},\"INTERACTION_USAGE\":{    \"usage_count\":4,\"usage_ms\":610644},\"SESSION_USAGE\":{\"usage_count\":4,    \"usage_ms\":615524},\"TRAN_ENUS\":{\"usage_count\":3,\"usage_ms\":187618},    \"VAD\":{\"usage_count\":2,\"usage_ms\":66900}}}}]}"

You can run the curl command line directly as shown on the console to send the report to LumenVox licensing in AWS and see the response, which should look something like this:

{"error":false,"response-message":"Success", "valid-license-guids":["XXXXXXXX-086f-42f0-a728-d95f39dc2229"], "report-signature":"XXXXXXXXXX5c40f307667eec8707f4e7ed152ea62c17d061a639cff79e2d92", "license-status-id":"XXXXXXXX-fc38-43a5-a10c-0e7dfd45da47"}

This can be used in the cluster-push operation described below.

operation: cluster-push

This operation is used to push the response from AWS into the running cluster, to update licensing. Note that the JSON response returned from the previous curl operation's curl request contains several quotes. These either need to be escaped (") or, a simpler solution is to place the JSON inside apostrophes ('...') instead, as shown below:

license-reporter-tool -operation "cluster-push" -deploymentId "XXXXXX-086f-42f0-a728-d95f39dc2229" -operatorId "XXXXXXX-bddb-4979-8284-531641b16eda" -responseJson '{"error":false,"response-message":"Success", "valid-license-guids":["XXXXXXXX-086f-42f0-a728-d95f39dc2229"], "report-signature":"XXXXXXX93d0a33ea93596bf02c6e423d373a1dab7a781bb10d3f0919aa", "license-status-id":"XXXXXX-96c6-4524-8c36-55e5f16e330b"}' -enableTls=true -reportingApiUri=reporting-api.XXXXXXXX.com:443

If this response is correctly validated by the license service in the running cluster, licensing will be enabled/refreshed, and you should see a response like this:

## performing LicenseStatusReportResponsePush to send response from cloud into ## cluster's license service... License Status Push Successful

Note: regular synchronization with the cloud licensing service (in AWS) is recommended to ensure correct licensing operation. Ideally this should be performed once daily to prevent unwanted outages.

Reminder Messages

After a set number of days without synchronization, the system will begin logging various messages, with increasing urgency, for the licenses to be synchronized. Failure to perform a regular license synchronization will eventually lead to the licenses becoming unusable, and the system to stop accepting and processing requests.

 ```shell 
{ 
     "level": "WARN", 
     "time": "2024-03-15T16:35:12.845-0700", 
     "message": "license synchronization required - please sync now", 
     "service": "license", 
     "days since last sync": 35 } 
``` 

There is also a Prometheus metric, from the license service, that shows the number of days since last successful synchronization: 

```shell 
# HELP license_days_since_sync Number of days since last valid license synchronization 
# TYPE license_days_since_sync gauge 
license_days_since_sync 35 
```
Was this article helpful?