Setting up the license reporter tool
The following page is for client systems that are air gapped and are unable to connect externally to the LumenVox licensing service at https://licensing.lumenvox.com via port 443.
Please speak to LumenVox support about getting access to the tool
This tool can be used by customers to get license information from the LumenVox cluster and report it to the licensing service (phone home).
It can also be used to send the response from the phone home reply into the LumenVox cluster.
This entire process is to allow a bypass mechanism that avoids using the direct phone-home connectivity so that customers can inspect the JSON being sent in and out from a security perspective.
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"
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 delpoymentId 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"
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"}'
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 LumenVox cloud licensing (in AWS) is recommended to ensure correct licensing operation. Ideally this should be performed once daily to prevent unwanted outages.
Nag messages
In March 2024, nag messages were added to remind users that a manual synchronization is needed to the LumenVox licensing server.
Now, the cutoff for license sync is 90 days. If no sync is performed within this number of days, licensing will shut off, and the license server will continue trying to sync. Nag messages will appear in the logs once per hour when licenses have expired (multiple messages will be shown, given the severity)
Warning messages will begin appearing in the logs after 30 day since the last sync: "license synchronization required - please sync now". This will be reported once per day.
Error messages will replace these after 60 days, and will be reported once per day: "license synchronization required - please sync now"
If no sync has been done when 80 days have passed since sync (meaning only 10 days remain) a critical error will be logged once per hour: "CRITICAL LICENSE SYNCHRONIZATION REQUIRED - PLEASE SYNC NOW TO PREVENT OUTAGE"
With each of these log messages will be an indicator showing how many days have passed since the last license sync, for example (formatted for clarity):
```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 }
``` Along with this change, there is also a new Prometheus metric that shows the number of days since last sync:
```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 ```