Device RMA¶
Overview¶
Use the Device RMA API to create a super-task to remove multiple module objects from the BIG-IQ’s working-config. To remove multiple modules, send a POST request to the device-remove-mgmt-authority task collection on the BIG-IQ. Specify the modules being removed in moduleList (firewall, security_shared, asm, adc_core, access, dns, fps or sslo). The API’s response can include the status for the super-task and for each individual module because the system runs a separate removal task for each module. If the required LTM (ADC) module is missing the entire super-task fails. Missing any other module does not cause failure and the super-task continues to remove the specified modules. This task can remove module objects from the working-config whether or not they have been discovered. Use the Device Import API to import copies of the module objects from the current-config to the working-config of the BIG-IQ. Use the Device Discovery API to determine what module objects exist on a single BIG-IP and then create corresponding copies of these module objects in the BIG-IQ’s current-config.
REST Endpoint: mgmt/cm/global/tasks/device-remove-mgmt-authority¶
Requests¶
To create a super-task which can remove multiple module objects from the BIG-IQ’s working-config, send a POST request to the device-remove-mgmt-authority endpoint.
POST mgmt/cm/global/tasks/device-remove-mgmt-authority¶
Request Parameters¶
The JSON in the body of the POST request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
description | string | False | An optional description for the super-task. |
deviceReference | object | True | The value of deviceReference is a link object for the BIG-IP targeted by this removal request. |
link | string | True | URL of deviceReference |
moduleList | object array | False | A list identifying the module objects to remove. The status fields of the module objects are not required in the POST request. Provide the module object identifier in module. Omitting moduleList means remove all modules. The easiest way to remove every module is to omit moduleList from the POST request. |
module | string | True | Module identifier. Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
name | string | False | An optional name for the super-task. |
Query Parameters¶
None
Response¶
The JSON in the body of the POST response can contain the following parameters. The super-task’s status in the initial response to the POST request can be “STARTED”, and to poll for the updated status you can send repeated GET requests to the selfLink of the task. The moduleList in the response to POST or GET can also contain information about the status of each individual module.
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
ItemState | object | State of the removal task. |
currentStep | string | Current step of the removal task. Possible values: “INIT”, “CHECK_REMOVED_MODULES”, “GET_DEVICE_IN_GROUPS”, “GET_DEVICE_IN-BIGIP_GROUP”, “CHECK_RUNNING_TASKS”, “CHECK_APPLICATIONS”, “CHECK_SCALING_GROUPS”, “PROCESS_MODULE_TASKS”, “DELETE_MODULE_TASKS”, “FAILED” or “DONE”. |
description | string | An optional description for the task. |
deviceReference | string | The value of deviceReference is a link object for the BIG-IP targeted by this removal request. |
link | string | URL of deviceReference |
endDateTime | string | The time the task stopped running. |
errorMessage | string | An error encountered while the task was running. There can be errors even when the task’s status is not “FAILED”. |
id | string | The id of the task. |
moduleList | object | List of modules being removed, with status. |
endTime | string | End time for module processing (UTC). |
errorMsg | string | Error message from module removal task. |
module | string | Module object identifier. Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
startTime | string | Start time for module processing (UTC). |
status | string | Final status of module-specific task. Possible values: “QUEUED”, “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
statusQual | string | If the module status is “FAILED”, this value can be “TASK_BUSY”, which indicates that the module removal task was already active. |
taskReference | string | Reference to module removal task. |
link | string | URL of the reference to module removal task. |
name | string | An optional name for the task. |
selfLink | string | The URL to access this item directly. |
startDateTime | string | The time the task was started. |
status | string | Standard task status of the super-task, updated during execution. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
userReference | string | The user that initiated the task. |
link | string | URL for userReference |
identityReferences | array | A list of user identities that initiated the task. |
link | string | URL for an user identity |
ownerMachineId | string | In a high-availability environment, the machineId of the host running the task. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker. |
parentTaskReference | object | The task API that initiated the task. |
link | string | URL for the task API that initiated the task. |
username | string | The user that initiated the task. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
GET /cm/global/tasks/device-remove-mgmt-authority/<id>¶
To check the status of a super-task you can send a GET request to the endpoint and specify the super-task’s id. The super-task’s id and selfLink can be obtained from the response to a previous GET request or from the response to the original POST used to create the super-task. The status of the individual module tasks are returned in moduleList.
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
ItemState | object | State of the removal task |
currentStep | string | Current step of the removal task. Possible values: “INIT”, “CHECK_REMOVED_MODULES”, “GET_DEVICE_IN_GROUPS”, “GET_DEVICE_IN-BIGIP_GROUP”, “CHECK_RUNNING_TASKS”, “CHECK_APPLICATIONS”, “CHECK_SCALING_GROUPS”, “PROCESS_MODULE_TASKS”, “DELETE_MODULE_TASKS”, “FAILED” or “DONE”. |
description | string | An optional description for the task. |
deviceReference | string | The device for modules being removed, as a machine id resolver device reference. |
link | string | URL of deviceReference |
endDateTime | string | The time the task stopped running. |
errorMessage | string | An error encountered while the task was running. There can be errors even when the task’s status is not “FAILED”. |
id | string | The id for the task. |
moduleList | object | List of module names of modules being removed, with status. |
endTime | string | End time for module processing (UTC). |
errorMsg | string | Error message from module removal task. |
module | string | Module object identifier. Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
startTime | string | Start time for module processing (UTC). |
status | string | Final status of module removal task. Possible values: “QUEUED”, “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
statusQual | string | If the module status is “FAILED”, this value can be “TASK_BUSY”, which indicates that the module removal task was already active. |
taskReference | string | Reference to module removal task. |
link | string | URL of the reference to module removal task. |
name | string | An optional name for the task. |
selfLink | string | The URL to access this item directly. |
startDateTime | string | The time the task was started. |
status | string | Standard task status of the super-task, updated during execution. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
userReference | string | The user that initiated the task. |
link | string | URL for userReference |
identityReferences | array | A list of user identities that initiated the task. |
link | string | URL for an user identity |
ownerMachineId | string | In a high-availability environment, the machineId of the host running the task. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker. |
parentTaskReference | object | The task API that initiated the task. |
link | string | URL for the task API that initiated the task. |
username | string | The user that initiated the task. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
PATCH mgmt/cm/global/tasks/device-remove-mgmt-authority/<id>¶
To cancel a running super-task, or restart a super-task with a “FINISHED” or “FAILED” status, you can send a PATCH request to the endpoint and specify the super-task’s id. To cancel a running super-task, send a PATCH request to change the value of status to “CANCEL_REQUESTED”. Then send a GET request to poll the super-task until the value of status updates to “CANCELLED”, “FINISHED”, or “FAILED”. The values “FINISHED” or “FAILED” indicate the request was sent too late to cancel the super-task. To restart a super-task having a status of “FINISHED” or “FAILED”, send a PATCH request to change the value of status to “STARTED” and optionally change moduleList.
Request Parameters¶
The JSON in the body of the PATCH request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
moduleList | array | False | When restarting a super-task in the “FINISHED” or “FAILED” state, you can optionally change the list of modules being removed by changing moduleList. Omitting moduleList means remove all modules. |
module | string | True | Module object identifier. Possible values are “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
status | string | True | Standard task status of the super-task, updated during execution. To cancel the super-task, this value can be changed to “CANCEL_REQUESTED”. To restart the super-task, this value can be “STARTED”. |
Response¶
HTTP/1.1 200 OK
The JSON in the body of the PATCH response can be similar to the GET response.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
DELETE /cm/global/tasks/device-remove-mgmt-authority/<id>¶
To delete a super-task you can send a DELETE request to the endpoint and specify the super-task’s id. The super-task’s id and selfLink can be obtained from the response to a previous GET request or from the response to the original POST used to create the super-task.
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
The JSON in the body of the DELETE response can be similar to the GET response.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
Examples¶
POST to remove multiple modules¶
POST https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-mgmt-authority
The following example creates a super-task to remove a module object from the BIG-IQ’s working-config. The JSON in the body of the POST can be similar to the following.
{
"name": "device-rma_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"moduleList": [{
"module": "firewall"
}]
}
Response¶
The JSON in the response to the POST can look similar to the following. The value of selfLink is the URL for the super-task. The value of status can be “STARTED” initially, which means the task has been started. To poll for the updated status, you can send repeated GET requests to the super-task’s selfLink. Note that the status of the module is returned in moduleList.
{
"name": "device-rma_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"currentStep": "DONE",
"moduleList": [{
"module": "firewall",
"status": "FINISHED",
"errorMsg": "Task https://localhost/mgmt/cm/firewall/tasks/remove-mgmt-authority/57e32353-5a91-470a-be34-a5ce1a17973a is still in process, wait for this task to complete.",
"startTime": "2019-08-26T19:04:13.722Z",
"endTime": "2019-08-26T19:04:16.769Z",
"taskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/remove-mgmt-authority/57e32353-5a91-470a-be34-a5ce1a17973a"
}
}],
"generation": 42,
"lastUpdateMicros": 1566831709720008,
"kind": "cm:global:tasks:device-remove-mgmt-authority:rmasupertaskitemstate",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-remove-mgmt-authority/5de37aee-0845-4fb3-aa94-48e020c43225",
"id": "5de37aee-0845-4fb3-aa94-48e020c43225",
"status": "STARTED",
"startDateTime": "2019-08-22T16:29:46.806-0400",
"endDateTime": "2019-08-22T16:30:03.471-0400",
"errorMessage": "Device in use by application 'sample'",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "24275453-2670-4acd-ac33-875aabcfc4bf",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {}
}
GET to check the task’s status¶
The following example gets the updated status for the super-task identified by id and selfLink. You can send repeated GET requests to check the status of the super-task, which can eventually update to “DONE” and “FINISHED”.
GET https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-mgmt-authority/<id>
Response¶
The JSON in the response to the GET when the task is done can look similar to the following. Note that the status of the module-specific task is included in moduleList.
{
"name": "device-rma_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"currentStep": "DONE",
"moduleList": [{
"module": "firewall",
"status": "FINISHED",
"errorMsg": "Task https://localhost/mgmt/cm/firewall/tasks/remove-mgmt-authority/57e32353-5a91-470a-be34-a5ce1a17973a is still in process, wait for this task to complete.",
"startTime": "2019-08-26T19:04:13.722Z",
"endTime": "2019-08-26T19:04:16.769Z",
"taskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/remove-mgmt-authority/57e32353-5a91-470a-be34-a5ce1a17973a"
}
}],
"generation": 42,
"lastUpdateMicros": 1566831709720008,
"kind": "cm:global:tasks:device-remove-mgmt-authority:rmasupertaskitemstate",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-remove-mgmt-authority/5de37aee-0845-4fb3-aa94-48e020c43225",
"id": "5de37aee-0845-4fb3-aa94-48e020c43225",
"status": "STARTED",
"startDateTime": "2019-08-22T16:29:46.806-0400",
"endDateTime": "2019-08-22T16:30:03.471-0400",
"errorMessage": "Device in use by application 'sample'",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "24275453-2670-4acd-ac33-875aabcfc4bf",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {}
}
PATCH to cancel a running super-task¶
You can send a PATCH request to cancel a running super-task specified by the task’s id.
PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-mgmt-authority/<id>
In the body of the PATCH request specify the value of status as “CANCEL_REQUESTED”.
{
"status": "CANCEL_REQUESTED"
}
Response¶
You can then send repeated GET requests to poll the super-task until the value of status updates to “CANCELLED”, “FINISHED”, or “FAILED”. The values “FINISHED” or “FAILED” indicate the request was sent too late to cancel the super-task.
PATCH to restart a super-task¶
You can send a PATCH request to restart a super-task having a status of “FINISHED” or “FAILED”. Specify the super-task to restart by the super-task’s id.
PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-mgmt-authority/<id>
In the body of the PATCH request specify the value of status as “STARTED”, and you can optionally change the value of moduleList.
{
"moduleList": [{
"module": "firewall"
}],
"status": "STARTED"
}
Response¶
You can then send repeated GET requests to poll the super-task until the value of status updates to “FINISHED” or “FAILED”.
DELETE to delete a removal task¶
The following example deletes the super-task identified by id.
DELETE https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-mgmt-authority/<id>
Response¶
The JSON in the response from a DELETE request is similar to a response from a GET request.