Licensing Initial Activation API

Overview

The Initial Activation API provides a common starting point for activating all pool-style licenses (Purchased Pool, Utility, Volume, and FPS licenses). You can use the API to perform the initial activation of the top-level pool and any offerings it may include. The API helps to avoid having know the type of particular registration key and which API should be used to activate it.

  • For automatic activation, the system gets the license text from the F5 license server. For manual activation, the API provides a dossier, which you can use to acquire license text from the F5 licensing web portal.
  • The API uses the license text to determine the type of license and with that, it creates an entry in the appropriate license collection. For instance, a purchased pool license registration key will result in an entry in cm/device/licensing/pool/purchased-pool/licenses.
  • For automatic activation, the API waits for the activation process to finish in the specific collection. This is typically a multi-step process, as each offering needs to be activated.
  • For manual activation, the process is more involved. As with automatic activation, an item will be created in the relevant license collection, but activation of any offerings must be completed via that license collection’s API.

Prerequisites

Make certain that the following prerequisites have been met.

  • The BIG-IQ Centralized Management device is operational, has completed the setup wizard, and completed any other needed configuration.
  • The BIG-IQ has an internet connection to the F5 licensing server if you plan to use automatic activation.
  • You have one of the following roles: administrator, device manager, or license manager.

Note: When you perform these tasks using the example code provided, review the listed IP addresses and change them as appropriate for your environment. For example, if you are not running the script directly on the BIG-IQ device, change localhost to be the IP address of the BIG-IQ Centralized Management device.

1. Start activation of a license

There are three methods to activate a license: automatic, manual and closed-circuit network (CCN). An example of an starting an automatic activation is shown here. For 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.

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

Request:

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

Response:

{
  "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"
}

2. Poll to get status

After initiating an activation, you should poll to check the activation status.

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

Response:

{
  "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",
  ...
}

3. Complete automatic activation by accepting the EULA

Echo the EULA text back to the license endpoint to agree to the EULA and complete the automatic activation workflow.

After doing so, again poll to get the final activation status (either READY or ACTIVATION_FAILED).

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

Request:

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

Response:

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

4. Complete manual activation by providing license text

If manual activation is used instead of automatic activation, then the PATCH to complete activation will include the license text received from the F5 licensing web portal.

Similar to automatic activation, you will need to poll to get the final activation status.

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

Request:

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

Response:

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

5. Retry a failed activation

If an activation fails, check error messages returned from the API or the restjavad logs for details.

Similar to the prior steps, you will need to poll to get the final activation status.

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

Request:

{
  "status": "ACTIVATING_AUTOMATIC"
}

Response:

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

6. Remove a failed activation

If desired, you can remove a failed activation attempt.

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

7. Confirm license is ready

After completing the initial activation process, the status will be READY and the API will provide a reference to the created license. Depending on the license type, activation of any offerings will still be required when using manual activation. Those activations will occur via the API endpoint noted in the reference. Purchased pool licenses do not require this additional step.

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

Response:

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

Following the reference to the new license:

GET {endpoint noted in licenseReference}

Response:

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

All other license types will look slightly different – with a status field instead of state. And if there are offerings under the license, they must be activated also (activation method will be the same as was used for the initial activation).

For an automatic activation, such an initial response will look like this:

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

After polling until offerings are activated, the response will indicate the license is fully ready:

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