Skip to main content

Licensing

Transcription:BatchReal-TimeDeployments:Virtual Appliance

The Speechmatics Virtual Appliance uses two licensing options: an online cloud-based licensing mechanism, and offline licensing. The online license requires that the Appliance must be connected to the Internet in order to activate the license, and then while running will need connection to the external Internet via Port 80.

An offline license allows a user to apply a license without ever connecting an Appliance to the external Internet, even to initially license the Appliance. Users generate an Activation Certificate via the Management API, which is then sent to Speechmatics Support to generate a separate license certificate. The license certificate can be used to then successfully generate transcription from the offline Appliance. How to do so is described in more detail below.

Your Appliance must have been activated with a valid license before the Speech API can be used. Use of the Management API does not require a license. Please reach out to Support if you do not have a license.

You can only apply one license to an Appliance at a time. If you want to apply a new license, you must first remove the old license, then apply a new license.

Licensing with the Enhanced Model​

If you are using both the Standard and the Enhanced model interchangeably, please note that you will need two separate licenses, one for Standard appliances which will be entitled to use a Standard model, and one for appliances that will be entitled to use a Standard and Enhanced model. You should ensure in your routing logic that jobs using the Standard model are sent to the Appliance which only uses the Standard model. Otherwise, there is a risk of overbilling. You will also require a new license to use the Enhanced model.

If you are not certain whether you are entitled to use the Enhanced model, please check with your Account Manager.

Applying an Online License​

To apply a license that you have received from Speechmatics you use a POST request to the Management API. If your license supports fully offline activation and your Appliance has no route to the Internet, then you should follow the instructions in the section on Offline License Activation later on. Otherwise keep reading this section.

Assuming your Appliance is deployed in a network that has a route to the Internet you can make the activations request to the /v1/management/license endpoint as follows:

  • Method: POST
  • URL:
    http://${APPLIANCE_HOST}:8080/v1/management/license
  • Body format: JSON
  • Body: license, username, email_address, company_name

You must supply the license value. The other fields (username, email_address and company_name) are optional, but we recommend that you fill them in with your details to help in case of Support issues.

Note: make sure when applying the license, that all the Appliance services are running; otherwise the activation will fail.

The example below shows how to make an activation call using the Management REST API:

curl -L -X POST "http://${APPLIANCE_HOST}:8080/v1/management/license" \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' \
   -d '{
       "license": "494953679762904933",
       "username": "Amy Liu",
       "email_address": "a-liu@example.com",
       "company_name": "Example Pty"
    }' \
   | jq

The response should indicate that the licensed status is true. The licensing activation requires a connection to the Internet (using TCP port 80). Blocking this port with an online license can cause transcription issues. If you are behind a corporate firewall that does not allow a direct connection to the Internet then you can configure the Appliance to use a proxy server to allow you to license the Appliance as shown in the documentation here.

Checking an Appliance License​

You can check whether the Appliance is licensed by using a GET request to the /license endpoint on the Management API. For example:

curl -L -X GET "http://${APPLIANCE_HOST}:8080/v1/management/license" \
    -H 'Accept: application/json' \
    | jq

Example Response (Unlicensed)​

If the Appliance has not been licensed then you will see something like this:

{
  "licensed": false,
  "product": "103",
  "subscription_expiry": "1970-01-01T00:00:00Z",
  "status": "-113 License status server trial expired",
  "message": "",
  "transcription_minutes_allowed": "0",
  "license_type": "",
  "activation_type": "",
  "transcription_secs_allowed": 0,
  "transcription_secs_allocated": 1800000,
  "connected": true,
  "customer_id": 4920,
  "license_code": ""
}

The licensed property is false, and the license_code property is empty, indicating that the Appliance has not yet been activated with a valid license code. The Appliance can be managed through the Management API whilst in this state, but any attempt to use the Speech API to transcribe speech will return a not authorised error with the reason "You are not authorised to perform this action: License is invalid".

Example Response (Licensed)​

If the Appliance has been licensed then you will see a return like this:

{
  "licensed": true,
  "product": "103",
  "subscription_expiry": "2021-10-16T12:26:37Z",
  "status": "3 License status concurrent license",
  "message": "",
  "transcription_minutes_allowed": "60",
  "license_type": "6 License is concurrent subscription",
  "activation_type": "1 License was activated online",
  "transcription_secs_allowed": 3600,
  "transcription_secs_allocated": 1800000,
  "connected": true,
  "customer_id": 4949,
  "license_code": "494913586168289666"
}

This shows that the Appliance has been licensed with code 494913586168289666. The license is due to expire on the 16th October 2021. 500 hours (1800000 seconds) have been allocated for use. A local cache of 1 hour (3600 seconds) is maintained on the Appliance to allow it to operate offline for limited periods of time; both of these values will be defined depending on your license requirements.

Removing a License​

If you no longer wish to use the Appliance, or you need to perform an upgrade to a newer version then you should first remove the license before powering down the Virtual Appliance. This will return any unused audio hours that you may have cached on the Appliance. You must be online to perform this action. Once the license is removed the Appliance will no longer be able to transcribe speech. You use an HTTP DELETE to remove the license:

curl -L -X DELETE "http://${APPLIANCE_HOST}:8080/v1/management/license" \
    -H 'Accept: application/json'
    | jq

The response shows the number of unused seconds that were returned for use by future activations, for instance:

{
  "transcription_secs_returned": 60780
}

Using a Proxy Server​

The Appliance needs to talk to the cloud licensing service using HTTP (TCP port 80). The license credentials are encrypted over this link. If the network the Appliance is installed on uses a proxy server to access the Internet, then you will need to configure the Appliance to use that proxy. This is a prerequisite before attempting to apply the license.

To configure the Appliance, use a POST to the /v1/management/license/network endpoint:

curl -X POST "http://${APPLIANCE_HOST}:8080/v1/management/license/network" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{ "http_configuration": {
        "ip": "${PROXY_HOST}",
        "port": "${PROXY_PORT}",
        "user": "${PROXY_USERNAME}",
        "password": "${PROXY_USERNAME}"
        }
    }' \
    | jq

Where ${PROXY_HOST} is the IP address or hostname of your proxy server, and ${PROXY_PORT} is the port number it uses. If you use username and password authentication for the proxy server, then these also need to be specified using the ${PROXY_USERNAME} and ${PROXY_PASSWORD} options. If the proxy server does not require authentication then they should be left out.

Once you have configured the Virtual Appliance to use your proxy server you will be able to activate the Appliance – see the section above on how to apply a new license.

Offline License Activation​

This section explains how to license your Appliance if it is in a completely offline environment (i.e. there is no route to the Internet), and you are not able to connect to the Internet even during initial activation of the license. If this is the case then you need to generate an activation certificate, send this to Support, and then apply the license certificate that is sent back. Follow the steps in this section to do this.

It is recommended as part of best practice where the Appliance cannot connect to the Internet to activate the license offline using the method below.

Generating an Activation Certificate​

The process is similar to online activation: you will receive a license code from Speechmatics Support. However, additional steps are required, and different endpoints on the Management API are used.

Offline activations require a POST request to the /v1/management/license/offlineactivation endpoint:

  • Method: POST
  • URL:
    http://${APPLIANCE_HOST}:8080/v1/management/license/offlineactivation
  • Body format: JSON
  • Body: license, username, email_address, company_name

Note: make sure when applying the license, that all the Appliance services are running; otherwise the activation will fail.

The example below shows how to make an offline activation call using a POST request to the Management REST API:

curl -L -X POST "http://${APPLIANCE_HOST}:8080/v1/management/license/offlineactivation" \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' \
   -d '{
       "license": "494853989762904933",
       "username": "Fiona Kelly",
       "email_address": "fjk@example.com"
    }' \
   | jq

Sending the Activation Certificate to Speechmatics​

The response contains a long string of alphanumeric characters. This is the activation certificate. You should save this as a text file and send to Support, along with the license code that you used.

Once this has been done, the Support Team will use the activation certificate to generate a license certificate. They will then send this back to you by email reply.

Note: You should make sure, when in the process of applying an offline license, that you do not reboot the Appliance between generating the activation certificate and applying the license certificate. The reason being that the computer identifier which is used as a component of the certificates will be different between reboots.

Applying the License Certificate​

Once you have been sent the license certificate by Speechmatics Support you can use this to activate the Appliance by making a PUT request to the /v1/management/license/offlineactivation endpoint:

  • Method: PUT
  • URL:
    http://${APPLIANCE_HOST}:8080/v1/management/license/offlineactivation
  • Body format: JSON
  • Body: license, certificate

Where certificate is the license certificate that Speechmatics Support have provided to you, and license is the original activation license code you received.

Note: It is important that you use the PUT method to send the license certificate to the Appliance. If you use the POST method you will end up with an error and will need to repeat the license activation process.

The example below shows how to make this activation call:

curl -L -X PUT "http://${APPLIANCE_HOST}:8080/v1/management/license/offlineactivation" \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' \
   -d '{
       "license": "494853989762904933",
       "certificate": "7bc3c6684....f46d9781cfbae3c8129505e"
    }' \
   | jq

Note: The certificate is a very long string of alphanumeric characters. We shorten this here for brevity.

Once the Appliance has been licensed in this way you will see a return like this:

{
  "licensed": true,
  "product": "100",
  "subscription_expiry": "2019-04-07T14:35:09Z",
  "status": "3 License status concurrent license",
  "message": "",
  "transcription_minutes_allowed": "2999",
  "license_type": "6 License is concurrent subscription",
  "activation_type": "1 License was activated online",
  "transcription_secs_allowed": 179998,
  "transcription_secs_allocated": 2147483647,
  "connected": false,
  "customer_id": 4948,
  "license_code": "494853989762904933",
  "computer_id": "bc8e7e32-7cc6-4292-83e5-555c726ae8d8",
  "error_message": ""
}

Running an Appliance Offline​

If you have activated your license offline, and have already processed the activation certificate using the steps described above, your Virtual Appliance will go into offline mode automatically, and will no longer need to talk to an external server.

If you have activated the Appliance online, but are expecting to run it in a completely 'dark' network (that is, your Appliance will not have any route to the Internet), then after you have activated the license online, you should put it into an offline mode. This is a quicker way of activating the license where the Appliance can be online for license activation only. Running the Appliance without an Internet connection is possible except for activating and deactivating your license, which must still be done when your Appliance is online. We recommend as best practice that you run licensing in offline mode if the Appliance will not have any route to the Internet.

Enabling offline mode can be done through the Management API by setting the offline state to true, like this:

curl -X POST "http://${APPLIANCE_HOST}:8080/v1/management/license/offlinemode" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{ "offline": true}' \
    | jq

Note: You can only use this mode if your license allows offline mode to be used. If offline mode is not supported by your license you will see an error message returned:

{
  "error": "Error happened in the license_management service: ModelException: Unknown Rpc Error. Status code=StatusCode.UNKNOWN: <_Rendezvous of RPC that terminated with:\n\tstatus = StatusCode.UNKNOWN\n\tdetails = \"Offline mode not enabled for this license\"\n\tdebug_error_string = \"{\"created\":\"@1544116759.516901870\",\"description\":\"Error received from peer\",\"file\":\"src/core/lib/surface/call.cc\",\"file_line\":1099,\"grpc_message\":\"Offline mode not enabled for this license\",\"grpc_status\":2}\"\n>",
  "code": 13
}

Note: Putting the Appliance into offline mode like this stops any online license checking, which means that any changes to your license will not be picked up until you disable offline mode and go back online.

If you think that you may need to run your Appliance in offline mode then please reach out to Support.

Licensing Troubleshooting​

Receiving Updates to a License​

In the case where Speechmatics has provided an update to an already activated license (for example, to increase the number of license activations, or the amount of audio hours allowed), then you will need to restart the services on your Appliance, and ensure that the Appliance is online when you do so, in order for the license updates to take effect.

Invalid License​

If you attempt to activate your Virtual Appliance by applying a license code, and you see this error message, then it means that the license code is invalid.

Input exception: Not activated

If this occurs please reach out to Support, sending back the full output from the activate license POST request.

Appliance Offline​

If you see the following error when attempting to activate the Appliance:

{
  "error": "Error happened in the license_management service: InputException: Cannot activate or reset license in offline mode",
  "code": 3,
  "message": "Error happened in the license_management service: InputException: Cannot activate or reset license in offline mode",
  "details": []
}

Then the Appliance is unable to contact the cloud license service. Make sure that you are able to reach the licensing service by pinging the following hostname: my.nalpeiron.com. If you use a proxy server to connect to the Internet, ensure that the Appliance has been configured to use the proxy (making sure that you specify at least the IP address or hostname of the proxy, and the correct port number). Look in the logs of your proxy server to check that the Appliance is using the correct proxy server. To check whether you are running online or not you can run the following:

curl -L -X GET "http://${APPLIANCE_HOST}:8080/v1/management/license" \
    -H 'Accept: application/json' \
    | jq '.connected'

Offline Activation Error​

If you are carrying out activation offline, and you use the POST method rather than a PUT to send the license certificate to the Appliance you will see a "code": 13 error with a description message of "Unable to request activation certificate: -1121". The full error response will look like this:

{
  "error": "Error happened in the license_management service: ModelException: Unknown Rpc Error. Status code=StatusCode.UNKNOWN: <_Rendezvous of RPC that terminated with:\n\tstatus = StatusCode.UNKNOWN\n\tdetails = \"Unable to request activation certificate: -1121\"\n\tdebug_error_string = \"{\"created\":\"@1738245024.927287214\",\"description\":\"Error received from peer\",\"file\":\"src/core/lib/surface/call.cc\",\"file_line\":1036,\"grpc_message\":\"Unable to request activation certificate: -1121\",\"grpc_status\":2}\"\n>",
  "code": 13
}

Unable to Delete License When Offline​

If you have activated a license online, but you then go into offline mode, you will get an error if you attempt to remove the license (DELETE /v1/management/license).

{
  "error": "Error happened in the license_management service: ModelException: Unknown Rpc Error. Status code=StatusCode.UNKNOWN: <_Rendezvous of RPC that terminated with:\n\tstatus = StatusCode.UNKNOWN\n\tdetails = \"Cannot remove license in offline mode\"\n\tdebug_error_string = \"{\"created\":\"@1738245024.927287214\",\"description\":\"Error received from peer\",\"file\":\"src/core/lib/surface/call.cc\",\"file_line\":1036,\"grpc_message\":\"Cannot remove license in offline mode\",\"grpc_status\":2}\"\n>",
  "code": 13
}

In order to remove the license you will need to exit offline mode, and make sure that there is a route to the Internet before trying to remove the license.

Virtual Appliance is Offline Message When Port 80 is Blocked​

Communication with the cloud license service relies on port 80 being open. If there is a firewall in your network that blocks port 80 then you will see error messages like this when attempting to make a licensing call:

{
  "error": "Error happened in the license_management service: ModelException: Unknown Rpc Error. Status code=StatusCode.CANCELLED: <_Rendezvous of RPC that terminated with:\n\tstatus = StatusCode.CANCELLED\n\tdetails = \"Received RST_STREAM with error code 8\"\n\tdebug_error_string = \"{\"created\":\"@1546953904.251876385\",\"description\":\"Error received from peer\",\"file\":\"src/core/lib/surface/call.cc\",\"file_line\":1099,\"grpc_message\":\"Received RST_STREAM with error code 8\",\"grpc_status\":1}\"\n>",
  "code": 13
}

In such cases make sure that port 80 is open, or configure the Appliance to use a proxy server.