License Initial Activation¶

Overview¶

You can use this API as a starting point for activating all pool-style licenses, such as Purchased Pool, Utility, Volume, and FPS licenses. Use this API to perform the initial activation of the top-level pool and any offerings it may include.

This API can make it easier to activate pool-style licenses because you do not need knowledge about the type of registration key. It uses the license text to determine the type of license and then creates a license entry in the appropriate license collection. For example, given a purchased pool license registration key this API creates a license in cm/device/licensing/pool/purchased-pool/licenses. To use this API you need to have an administrator, device manager, or license manager role.

There are three methods to activate a license: automatic, manual and closed-circuit network (CCN). For automatic activation, this API gets the license text from the F5 license server. If you use automatic activation, the BIG-IQ requires an internet connection to the F5 licensing server. For manual activation, this API provides a dossier, which you can then use to retrieve the license text from the F5 licensing web portal. Manual activation can require additional steps to activate any offerings. These additional steps must be completed using the API for the specific license collection. CCN activation requires opening a support case with F5.

You can assign a BIG-IP to be a license member after the license has been activated using the License Assign/Revoke API or the Purchased Pool License Members API.

REST Endpoint: /mgmt/cm/device/licensing/pool/initial-activation¶

Requests¶

POST /mgmt/cm/device/licensing/pool/initial-activation¶

To start activation, send a POST to the initial-activation collection endpoint. The JSON in the body can contain the following parameters.

Request Parameters¶

Name	Type	Required	Description
name	string	Yes	Name you have chosen for this license.
regKey	string	Yes	The value of your registration key.
status	string	Yes	The status of the activation. Use “ACTIVATING_AUTOMATIC” to start automatic activation. Use “ACTIVATING_MANUAL” to start manual activation.

Query Parameters¶

None

Response¶

The JSON in the POST’s response can include the following parameters.

HTTP/1.1 200 OK

Name	Type	Description
dossier	string	For manual activation, this provides a dossier you can use to retrieve the license text from the F5 licensing web portal.
encryptedPrivateKey	array	A value for internal use.
internalPrivateKey	string	A value for internal use.
message	string	A description of the activation’s progress. For example, this can be “Automatic activation in progress” for automatic activation.
name	string	A name you choose to use to identify this license.
publicKey	array	A value for internal use.
regKey	string	Your registration key.
selfLink	string	A url to the activation’s endpoint. You can poll for the status of this specific activation by sending a GET request to this url.
sortName	string	This value is used by the UI.
status	string	The initial status of the activation in the POST’s response. For automatic activation this is “ACTIVATING_AUTOMATIC”. For manual activation this is “ACTIVATING_MANUAL”.

Permissions¶

Role	Allow
device_manager	Yes
License_Manager	Yes

After starting the activation, you can send GET requests to the activation’s endpoint to confirm that the activation is progressing. For example, for automatic activation status in the GET response can transition from “ACTIVATING_AUTOMATIC” to “ACTIVATING_AUTOMATIC_NEED_EULA_ACCEPT”.

GET /mgmt/cm/device/licensing/pool/initial-activation/<regKey>¶

After starting the activation, you can poll the activation’s status by sending a GET requests to the activation’s endpoint.

Request Parameters¶

None

Query Parameters¶

None

Response¶

HTTP/1.1 200 OK

Name	Type	Description
eulaText	string	The text of the end user license agreement (EULA).
message	string	A short description of the activation progress which can include a request to accept the EULA or provide the license text. For example, for an automatic activation this can be: “Accept EULA to continue”.
status	string	The current status of the activation. “ACTIVATING_AUTOMATIC_NEED_EULA_ACCEPT” means accept the EULA to continue with automatic activation. “ACTIVATING_MANUAL_LICENSE_TEXT_PROVIDED” means provide the license text to continue manual activation. “ACTIVATION_FAILED” means activation has failed and you can try to correct and retry or remove the failed activation. “READY” means the activation completed and you can check the body of the GET response for a licenseReference to the activated license.
licenseReference	object	A reference to the activated license. The licenseReference is provided after the value of status has updated to “READY”. Depending on the license type, manual activation of any offerings will still be required. Those activations will occur through the API endpoint noted in the reference. Purchased pool licenses do not require this additional step. You can confirm the state of the activated license by sending a GET request to the licenseReference url.
link	string	The url to the activated license.

Permissions¶

Role	Allow
device_manager	Yes
License_Manager	Yes

PATCH /mgmt/cm/device/licensing/pool/initial-activation/<regKey>¶

After starting activation, you can continue, complete, or retry the activation by sending a PATCH request.

Request Parameters¶

Name	Type	Required	Description
eulaText	string	Yes to accept the EULA and continue automatic activation.	The text of the end user license agreement (EULA).
licenseText	string	Yes to provide the license text and continue manual activation.	The license text received from the F5 licensing web portal.
status	string	Yes	To accept the EULA and continue automatic activation, set this value to “ACTIVATING_AUTOMATIC_EULA_ACCEPTED” and include eulaText in the body of the PATCH request. To continue manual activation, set this value to “ACTIVATING_MANUAL_LICENSE_TEXT_PROVIDED” and include licenseText in the body. If this is a retry of a failed activation, this value can be “ACTIVATING_AUTOMATIC” or “ACTIVATING_MANUAL”.

Query Parameters¶

None

Response¶

The response to the PATCH can contain the following parameters.

HTTP/1.1 200 OK

Name	Type	Description
message	string	For an automatic activation, the value can be “Finishing activation”. For a manual activation the value can be “Regkey MY-REGISTRATION-KEY activated - populating collection”.
status	string	For an automatic activation, the value in this field is initially “ACTIVATING_AUTOMATIC_EULA_ACCEPTED”. For a manual activation, the value in this field is initially “ACTIVATING_MANUAL_LICENSE_TEXT_PROVIDED”.

After receiving the initial response to the PATCH, you should then send GET requests to check that status has updated to the final status value of “READY” or “ACTIVATION_FAILED”.

Permissions¶

Role	Allow
device_manager	Yes
License_Manager	Yes

DELETE /mgmt/cm/device/licensing/pool/initial-activation/<regKey>¶

You can remove an activation from the collection by sending a DELETE request to the endpoint of the specific activation.

Request Parameters¶

None

Query Parameters¶

None

Response¶

HTTP/1.1 200 OK

The JSON in the body of the response is for the deleted item.

Permissions¶

Role	Allow
device_manager	Yes
License_Manager	Yes

Examples¶

When you apply the following example code to your own tasks, change the IP addresses to values appropriate for your environment. For example, if you are not running the script directly on the BIG-IQ, change localhost to be the IP address of the BIG-IQ.

POST to start activation¶

To start activation of a license send a POST request to the activation collection.

POST https://<BIG-IQ>/mgmt/cm/device/licensing/pool/initial-activation

The body of the POST request can look similar to the following example for starting automatic activation. To start manual activation, set status to “ACTIVATING_MANUAL”. CCN activation requires opening a support case with F5. Replace “MY-REGISTRATION-KEY” in this example with your actual registration key.

{
    "regKey": "MY-REGISTRATION-KEY",
    "name": "my own freeform name",
    "status": "ACTIVATING_AUTOMATIC"
}

Response¶

The body of the response to the POST request can contain a selfLink to the specific activation which you can poll to check the activation status.

{
    "regKey": "MY-REGISTRATION-KEY",
    "sortName": "Pending",
    "publicKey": [
      -84,
      1,
      -48,
      ...
    ],
    "internalPrivateKey": "UAYLtswdQo...",
    "encryptedPrivateKey": [
      -125,
      -3,
      103,
      ...
    ],
    "name": "my own freeform name",
    "message": "Automatic activation in progress",
    "dossier": "60b0eaaa7q...",
    "status": "ACTIVATING_AUTOMATIC",
    "generation": 1,
    "lastUpdateMicros": 1488929240559574,
    "kind": "cm:device:licensing:pool:initial-activation:initialactivationworkeritemstate",
    "selfLink": "https://localhost/mgmt/cm/device/licensing/pool/initial-activation/MY-REGISTRATION-KEY"
}

GET to poll activation status¶

After starting activation, send GET request to poll for the activation’s status. You should continue polling until the response indicates the activation is ready to continue.

GET https://<BIG-IQ>/mgmt/cm/device/licensing/pool/initial-activation/MY-REGISTRATION-KEY

Response¶

When activation is ready to continue, the JSON in the response can look similar to the following example. Note that the response includes instructions to accept the EULA to continue.

{
    "eulaText": "END USER LICENSE AGREEMENT\r\nDOC-0355-08\r\n\r\nIMPORTANT - READ BEFORE...",
    "message": "Accept EULA to continue",
    "status": "ACTIVATING_AUTOMATIC_NEED_EULA_ACCEPT",
    ...
}

PATCH to accept the EULA¶

To continue automatic activation you can send a PATCH request to the endpoint of the specific activation.

PATCH https://<BIG-IQ>/mgmt/cm/device/licensing/pool/initial-activation/MY-REGISTRATION-KEY

To accept the EULA and continue automatic activation, the JSON in the PATCH request can look similar to the following example.

{
    "status": "ACTIVATING_AUTOMATIC_EULA_ACCEPTED",
    "eulaText": "END USER LICENSE AGREEMENT\r\nDOC-0355-08\r\n\r\nIMPORTANT - READ BEFORE..."
}

Response¶

The initial response to the PATCH request can indicate that the activation is continuing.

HTTP/1.1 200 OK

{
    "message": "Finishing activation",
    "status": "ACTIVATING_AUTOMATIC_EULA_ACCEPTED"
}

Again poll for the status of the activation by sending a GET request to the specific activation. The activation process has completed when the value of status transitions to “READY” or “ACTIVATION_FAILED”.

PATCH to provide license text and continue manual activation¶

To continue manual activation you can send a PATCH request to the specific activation.

PATCH https://<BIG-IQ>/mgmt/cm/device/licensing/pool/initial-activation/MY-REGISTRATION-KEY

For manual activation, the PATCH request can provide the license text received from the F5 licensing web portal. The JSON in the body of the PATCH request can look similar to the following example.

{
    "status": "ACTIVATING_MANUAL_LICENSE_TEXT_PROVIDED",
    "licenseText": "..."
}

Response¶

The initial response to the PATCH request can indicate the activation is continuing.

HTTP/1.1 200 OK

{
    "message": "Regkey MY-REGISTRATION-KEY activated - populating collection",
    "status": "ACTIVATING_MANUAL_LICENSE_TEXT_PROVIDED",
    ...
}

You can poll for the status of the activation by sending a GET request to the specific activation. The activation process has completed when the value of status in the response has transitioned to “READY” or “ACTIVATION_FAILED”.

PATCH to retry a failed activation¶

If an activation fails, check the error messages returned from the API and the restjavad logs. To retry, correct the errors and send a PATCH request to the specific activation.

PATCH https://<BIG-IQ>/mgmt/cm/device/licensing/pool/initial-activation/MY-REGISTRATION-KEY

To retry automatic activation, the value of status can be “ACTIVATING_AUTOMATIC”. To retry manual activation, the value of status can be “ACTIVATING_MANUAL”. For example, the JSON in the body of a PATCH request for automatic activation can look similar to the following example.

{
    "status": "ACTIVATING_AUTOMATIC"
}

Response¶

The initial response to the PATCH request can indicate that the activation is continuing.

HTTP/1.1 200 OK

{
    "message": "Automatic activation in progress",
    "status": "ACTIVATING_AUTOMATIC",
            ...
}

You can poll for the status of the activation by sending a GET request to the specific activation endpoint. The activation process has completed when the value of status transitions to “READY” or “ACTIVATION_FAILED”.

DELETE to remove a failed activation¶

To remove a failed activation, send a DELETE request to the specific activation.

DELETE https://<BIG-IQ>/mgmt/cm/device/licensing/pool/initial-activation/MY-REGISTRATION-KEY

Response¶

HTTP/1.1 200 OK

The JSON in the body of the response is for the deleted activation.

GET to confirm the license is ready¶

First, confirm that the activation process has completed and that the API has activated a license in the license collection. Send a GET request to the activation endpoint as follows and substitute your license registration key for “MY-REGISTRATION-KEY”.

GET https://<BIG-IQ>/mgmt/cm/device/licensing/pool/initial-activation/MY-REGISTRATION-KEY

Response¶

After completing the activation process, the value of status will be “READY” and there will be a licenseReference value present for the activated license. For example, the body of the GET’s response can look similar to the following.

{
    "licenseReference": {
      "link": "https://localhost/mgmt/cm/device/licensing/pool/purchased-pool/licenses/{uuid}"
    },
    "status": "READY",
    ...
}

Second, you can send a GET to the link in the licenseReference to confirm the activation of the license. For this purchased pool license example, the request can look as follows.

GET https://<BIG-IQ>/mgmt/cm/device/licensing/pool/purchased-pool/licenses/{uuid}

The JSON in the GET’s response contains the state of the created license. The value of state is “LICENSED” for a license which is ready to be assigned to a BIG-IP.

{
    "state": "LICENSED",
    "totalDeviceLicenses": 25,
    ...
}

Other license types can look slightly different and have a status instead of state. If there are offerings under the license, these must also be activated. You should use the same process for activating the offerings, automatic or manual, as used for activating the license. For example, for automatic activation the JSON in the response can be similar to the following until the license is fully ready.

{
    "status": "ACTIVATING_AUTOMATIC_OFFERINGS",
    ...
}

You can continue to send GET requests the the endpoint to determine when the value of status updates to “READY”, which means the license is fully ready.

{
    "status": "READY",
    ...
}

Depending on the license type, manual activation of offerings requires additional steps which will occur through the API endpoint noted in the licenseReference. Purchased pool licenses do not require this additional step.

Previous Next