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