License Assign/Revoke¶

Overview¶

You can use this API to assign and revoke pool licenses on a BIG-IP VE from a BIG-IQ. When assigning or revoking a pool license on a managed BIG-IP, this API does not require knowledge of the deviceReference of the managed BIG-IP or the reference of the license. This API can be used with all types of pool licenses except Fraud Protection Service (FPS) licenses.

To assign a license to a BIG-IP, the license must first be activated and be ready to be assigned by BIG-IQ. For example this can mean the EULA has been accepted and the license is registered with the license server. You can activate pool licenses using the License Initial Activation API. You can also activate a purchased pool license using the Purchased Pool Licenses API. You can activate RegKey pool license offerings using the RegKey Pool License Offerings API.

REST Endpoint: /mgmt/cm/device/tasks/licensing/pool/member-management¶

Requests¶

GET /mgmt/cm/device/tasks/licensing/pool/member-management¶

Request Parameters¶

None

Query Parameters¶

None

Response¶

The JSON in the body of a GET response can contain the following parameters.

HTTP/1.1 200 OK

Name	Type	Description
address	string	The IP address used to add the BIG-IP to BIG-IQ. This is sometimes called the discovery address.
command	string	The task’s action. The value can be “assign” or “revoke”.
currentStep	string	The current step of the task as predicated by state. For example the value can be “POLL_ASSIGNMENT_STATUS” or “GET_LICENSE”.
endDateTime	string	Formatted Date/Time when the task ended. For example, “2017-06-14T23:46:04.532-0700”.
id	string	Unique identifier assigned to this assign or revoke license task.
identityReferences	object	List of users
link	string	Array of reference links to users authorized to assign or revoke license.
licenseAssignmentReference	object	The reference to the resulting assignment.
link	string	A url to the reference to the assignment.
licensePoolName	string	A name given to the license pool.
ownerMachineId	string	Machine id of the BIG-IP.
selfLink	string	The url for the assign or revoke task.
skuKeyword1	string	An optional offering name.
skuKeyword2	string	An optional offering name.
startDateTime	string	Formatted Date/Time when the task started. For example, “2017-06-14T23:46:04.532-0700”.
status	string	The task’s status. For example, the value can be “STARTED”, “FINISHED” or “FAILED”.
userReference	object	Reference link to user.
link	string	A url to user.
username	string	The name of the user.

Permissions¶

Role	Allow
device_manager	Yes
License_Manager	Yes

POST /mgmt/cm/device/tasks/licensing/pool/member-management¶

To create an assignment or revoke task, you can send a POST request to the pool/member-management collection.

Request Parameters¶

Name	Type	Required	Description
address	string	Yes	The discovery address used to add the BIG-IP to BIG-IQ.
assignmentType	string	No	The type of assignment, which is determined by whether the BIG-IP is unreachable, unmanaged, or managed by BIG-IQ. Possible values: “UNREACHABLE”, “UNMANAGED”, or “MANAGED”.
chargebackTag	string	No	An optional text string which can be used as a charge back tag.
command	string	Yes	The task’s action. This value can be “assign” or “revoke”.
hypervisor	string	Yes for an unreachable BIG-IP.	Identifies the platform running the BIG-IP VE. Possible values: “aws”, “azure”, “gce”, “vmware”, “hyperv”, “kvm”, or “xen”.
licensePoolName	string	Yes	A name given to the license pool.
macAddress	string	Yes for an unreachable BIG-IP.	Ihe MAC address of the BIG-IP.
password	string	Yes for an unmanaged BIG-IP.	A password for an unmanaged BIG-IP. You must provide credentials when performing license operations on an unmanaged BIG-IP because BIG-IQ cannot use device trust. BIG-IQ communicates with unmanaged BIG-IPs solely for licensing purposes.
skuKeyword1	string	No	An optional offering name.
skuKeyword2	string	No	An optional offering name.
tenant	string	No	For an unreachable BIG-IP, you can provide an optional description for the assignment in this field.
unitOfMeasure	string	Yes for the assignment of a utility license.	The units used to measure billing. For example, “hourly” or “daily”.
user	string	Yes for an unmanaged BIG-IP.	A user for an unmanaged BIG-IP. You must provide credentials when performing license operations on an unmanaged BIG-IP because BIG-IQ cannot use device trust. BIG-IQ communicates with unmanaged BIG-IPs solely for licensing purposes.

Query Parameters¶

None

Response¶

HTTP/1.1 200 OK

Name	Type	Description
address	string	The discovery address used to add the BIG-IP to BIG-IQ.
command	string	The task’s action. The value can be “assign” or “revoke”.
currentStep	string	The current step of the task as predicated by state. For example the value can be “POLL_ASSIGNMENT_STATUS” or “GET_LICENSE”.
endDateTime	string	Formatted Date/Time when the task ended. For example, “2017-06-14T23:46:04.532-0700”.
id	string	Unique identifier assigned to this assign or revoke task.
identityReferences	object	List of users
link	string	Array of reference links to users authorized to assign or revoke license.
licenseAssignmentReference	object	Present if the assignment task is successful. The final task status will be “FINISHED” and licenseAssignmentReference will reference the resulting assignment.
link	string	A url to the license assignment.
licensePoolName	string	Name given to the license pool.
ownerMachineId	string	Machine id of the BIG-IP.
selfLink	string	The url for the assign or revoke task.
skuKeyword1	string	An optional offering name.
skuKeyword2	string	An optional offering name.
startDateTime	string	Formatted Date/Time when the task started. For example, “2017-06-14T23:46:04.532-0700”.
status	string	The task’s status. For example, the value can be “STARTED”, “FINISHED” or “FAILED”.
userReference	object	Reference link to user.
link	string	A url to user.
username	string	The name of the user.

Permissions¶

Role	Allow
device_manager	Yes
License_Manager	Yes

Examples¶

POST to assign a purchased pool license to a managed BIG-IP¶

Managed BIG-IPs are included in BIG-IQ’s inventory of trusted devices. This means BIG-IQ can perform operations on these BIG-IPs such as licensing, backups, upgrades, and configuration management. To assign a purchased pool license to a managed BIG-IP, you can provide the name of the pool and the discovery address of the BIG-IP. The discovery address is the address used to add the BIG-IP to BIG-IQ.

POST https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management

The JSON in the body of the POST can look similar to the following example.

{
     "licensePoolName": "pool name",
     "command": "assign",
     "address": "192.0.2.1"
}

Response¶

The response to the POST can look similar to the following example.

HTTP/1.1 200 OK

{
     "licensePoolName": "pool name",
     "command": "assign",
     "address": "192.0.2.1",
     "id": "d717c6a1-f3bd-46cb-8410-c6fda58940b9",
     "status": "STARTED",
     "userReference": {
         "link": "https://localhost/mgmt/shared/authz/users/lm"
     },
     "identityReferences": [
         {
            "link": "https://localhost/mgmt/shared/authz/users/lm"
         }
     ],
     "ownerMachineId": "b814fef0-2e8b-460d-af43-0d100dc50352",
     "taskWorkerGeneration": 1,
     "generation": 1,
     "lastUpdateMicros": 1497509153046646,
     "kind": "cm:device:tasks:licensing:pool:member-management:devicelicensingassignmenttaskstate",
     "selfLink": "https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management/d717c6a1-f3bd-46cb-8410-c6fda58940b9"
}

Note that the JSON in the body of the response includes the task’s id and an initial status of STARTED. All assignment operations involve starting the task using a POST, after which you should send GET requests to the task’s endpoint and poll for the task’s status until the task completes. Polling for this example would look as follows.

GET https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management/d717c6a1-f3bd-46cb-8410-c6fda58940b9

POST to assign a pool license offering to a managed BIG-IP¶

Pool licenses, which are not purchased pool licenses, can have offerings under the top-level pool. For example, a utility license can have a F5-BIG-MSP-BT-1G-LIC-DEV offering. This offering’s name indicates the features and throughput of the offering, which is typical for offering names. The BT indicates the good/better/best feature and 1G indicates the throughput. Each of the registration keys in a RegKey pool is an offering.

The API provides two optional fields which you can use to specify which offering to assign, skuKeyword1 and skuKeyword2. The API compares the values of these fields against the offering names in the pool and searches for a matching name of an available offering to assign. Licenses in a RegKey Pool that have already been assigned to a BIG-IP are skipped. You can provide values for one, both, or neither field. If you provide both, the first value must appear before the second in the name. If the search matches multiple available offerings, the API assigns the first offering. If searching by feature or throughput is not specific enough to differentiate between names, you can include other characters in skuKeyword1 and skuKeyword2. For example, you can include dashes and characters to differentiate between an offering with the feature “B” and another offering name containing “F5-BIG”.

The unitOfMeasure field is required to assign an utility license. This value specifies the units used to to measure billing. For example, “hourly” or “daily”. The following is an example of an assignment of a utility license offering.

POST https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management

The JSON in the POST request can look similar to the following.

{
    "licensePoolName": "u1",
    "command": "assign",
    "address": "192.0.2.1",
    "skuKeyword1": "BT",
    "skuKeyword2": "1G",
    "unitOfMeasure": "daily"
}

Response¶

HTTP/1.1 200 OK

The response and need for polling for final status is similar to the purchased pool example shown above. Note that the body contains the value of the task’s id and an initial status of STARTED. All assignment operations involve initiating a task, after which you should poll for task completion.

POST to assign of a license from a regkey pool¶

The following is an example of the assignment of a license from a regkey pool.

POST https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management

The JSON in the body of the POST request can look similar to the following example.

{
    "licensePoolName": "rgp1",
    "command": "assign",
    "address": "192.0.2.1",
    "skuKeyword1": "I3242"
}

Response¶

HTTP/1.1 200 OK

The response and to poll for the assignment task’s final status is similar to the previous examples. All assignment operations involve starting the task using a POST, after which you should send GET requests to the task’s endpoint and poll for the task’s status until the task completes.

POST to assign a license to an unmanaged BIG-IP¶

Unmanaged BIG-IPs are BIG-IPs that BIG-IQ communicates with solely for licensing purposes. Because these BIG-IPs are not actively managed using device trust, you must provide user credentials when assigning a license to an unmanaged BIG-IP.

The following is an example of the assignment of a license to an unmanaged BIG-IP.

POST https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management

The JSON in the body of the POST request can look similar to the following example. If you are also using a BIG-IP configured with an ssl-port which is different than 443, you can specify the port using the optional port field.

{
    "licensePoolName": "pool name",
    "command": "assign",
    "address": "192.0.2.1",
    "user": "admin",
    "password": "password"
}

Response¶

HTTP/1.1 200 OK

POST to assign a license to an unreachable BIG-IP¶

If BIG-IQ has no direct communication with a BIG-IP, the BIG-IP can be described as an unreachable BIG-IP. The BIG-IQ can generate licenses for an unreachable BIG-IP if the client has some means to install the provided license onto the BIG-IP manually or through the BIG-IP API. The BIG-IQ is required to specify that the assignmentType is “UNREACHABLE” and provide the BIG-IP’s MAC address and the platform on which which is running the BIG-IP. The BIG-IQ does not need to have knowledge of the unreachable BIG-IP’s credentials. You can also provide an optional description for the assignment using the tenant field. For this use case, the address does not need to be unique across BIG-IPs.

POST https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management

The JSON in the body of the POST can look similar to the following example.

{
    "licensePoolName": "pool name",
    "command": "assign",
    "address": "192.0.2.1",
    "assignmentType": "UNREACHABLE",
    "macAddress": "FA:16:3E:1B:6D:32",
    "hypervisor": "vmware",
    "tenant": "Marketing BU#15"
}

Response¶

HTTP/1.1 200 OK

After polling for task completion, if the assignment is successful, the body includes a licenseText field. Note that the license will be formatted for JSON output; if your client doesn’t handle this, you will need to substitute newline characters. This license can then be installed on the BIG-IP manually or by using the BIG-IP API. The license will eventually reside within the /config/bigip.license file on the BIG-IP. If placed directly in the bigip.license file, BIG-IP’s reloadlic command will load the new license. If the provided MAC address or platform/hypervisor are incorrect, BIG-IP can reject the license.

POST to revoke a license from a managed BIG-IP¶

Similar to the assignment operations, revoking a license involves initiating a task, after which you can poll for task completion.

POST https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management

The JSON in the body of the POST request can look similar to the following example.

{
    "licensePoolName": "pool name",
    "command": "revoke",
    "address": "192.0.2.1"
}

Response¶

HTTP/1.1 200 OK

POST to revoke a license from an unmanaged BIG-IP¶

BIG-IQ communicates with unmanaged BIG-IPs are BIG-IPs that BIG-IQ communicates with solely for licensing purposes. Because unmanaged BIG-IPs are not actively managed using device trust, you must provide user credentials when revoking a license on an unmanaged BIG-IP.

The following is an example of the revoking of a license from an unmanaged BIG-IP.

POST https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management

The JSON in the body of the POST can look similar to the following example. You can also supply the port, if needed.

{
    "licensePoolName": "pool name",
    "command": "revoke",
    "address": "192.0.2.1",
    "user": "admin",
    "password": "password"
}

Response¶

HTTP/1.1 200 OK

POST to revoke a license from an unreachable BIG-IP¶

If BIG-IQ has no direct communication with a BIG-IP, the BIG-IP can be described as an unreachable BIG-IP. The BIG-IQ can revoke licenses for an unreachable BIG-IP. The BIG-IQ is required to specify that the assignmentType is “UNREACHABLE” and provide the BIG-IP’s MAC address and the platform on which which is running the BIG-IP. The BIG-IQ does not need to have knowledge of the unreachable BIG-IP’s credentials. You can also provide an optional description for the assignment using the tenant field. For this use case, the address does not need to be unique across BIG-IPs.

POST https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management

The JSON in the body of the POST request can look similar to the following example.

{
    "licensePoolName": "pool name",
    "command": "revoke",
    "address": "192.0.2.1",
    "assignmentType": "UNREACHABLE",
    "macAddress": "FA:16:3E:1B:6D:32",
    "hypervisor": "vmware",
    "tenant": "Marketing BU#15"
}

Response¶

HTTP/1.1 200 OK

GET to poll for task completion¶

All assignment operations involve starting the task using a POST, after which you should send GET requests to the task’s endpoint and poll for the task’s status until the task completes. If successful, the final task status will be “FINISHED” and the licenseAssignmentReference will contain the reference to the resulting assignment. If the task fails, the final task status will be “FAILED” and errorMessage will be populated with the details. You can review restjavad logs for additional detail as needed. Note that although a status of “FINISHED” indicates that the BIG-IP has accepted and installed the license, subsequent MCP validation on BIG-IP can still reject the license. Therefore you may also need to validate that the BIG-IP is operational after the task completes.

Polling can look similar to the following example.

GET https://<BIG-IQ>/mgmt/cm/device/tasks/licensing/pool/member-management/d717c6a1-f3bd-46cb-8410-c6fda58940b9

Response¶

The response to the GET can look similar to the following.

{
    "address": "192.0.2.1",
    "command": "assign",
    "currentStep": "POLL_ASSIGNMENT_STATUS",
    "endDateTime": "2017-06-14T23:46:04.532-0700",
    "generation": 7,
    "id": "d717c6a1-f3bd-46cb-8410-c6fda58940b9",
    "identityReferences": [
        {
            "link": "https://localhost/mgmt/shared/authz/users/lm"
        }
    ],
    "kind": "cm:device:tasks:licensing:pool:member-management:devicelicensingassignmenttaskstate",
    "lastUpdateMicros": 1497509164582382,
    "licenseAssignmentReference": {
        "link": "https://localhost/mgmt/cm/device/licensing/pool/purchased-pool/licenses/9a79bcf5-906e-4418-83c2-190ea22b9ec8/member-management/9847bfb5-f0a4-474b-b978-04586fc6d17d"
    },
    "licensePoolName": "pool name",
    "ownerMachineId": "b814fef0-2e8b-460d-af43-0d100dc50352",
    "selfLink": "https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management/d717c6a1-f3bd-46cb-8410-c6fda58940b9",
    "skuKeyword1": "",
    "skuKeyword2": "",
    "startDateTime": "2017-06-14T23:45:53.063-0700",
    "status": "FINISHED",
    "userReference": {
        "link": "https://localhost/mgmt/shared/authz/users/lm"
    },
    "username": "lm"
}

Example of a failed response:

{
    "address": "192.0.2.1",
    "command": "assign",
    "currentStep": "GET_LICENSE",
    "endDateTime": "2017-06-14T23:57:10.608-0700",
    "errorMessage": "License pool 'bad pool name' not found",
    "id": "dee9bd7a-7760-452e-ab61-93df87f5cf36",
    "licensePoolName": "bad pool name",
    "status": "FAILED",
    ...
}

GET to view outstanding assignments¶

The below example shows how to view all outstanding assignments across licenses.

GET https://<BIG-IQ>/mgmt/cm/device/licensing/assignments

Response¶

The response to the POST can look similar to the following.

  {
"totalItems": 1,
"items": [
      {
      "assignmentType": "UNREACHABLE",
      "auditRecordReference": {
        "link": "https://localhost/mgmt/cm/device/licensing/audit/e1f14034-8e3b-4ede-bba5-acb56afb71a7"
      },
      "deviceAddress": "192.0.2.1",
      ...
      }
      ...
  }

Previous Next