Device Remove Trust¶
Overview¶
Use the Device Remove Trust API to remove a trust relationship between BIG-IQ and a BIG-IP. The untrusted BIG-IP can then have no modules or services imported or discovered. This also removes data related to the BIG-IP, for example the BIG-IP’s membership in various device groups. Use the Device Establish Trust API to establish a trust relationship between BIG-IQ and a BIG-IP.
REST Endpoint: mgmt/cm/global/tasks/device-remove-trust¶
Requests¶
To create a task to remove the trust relationship between BIG-IQ and a BIG-IP, send a POST request to the device-remove-trust endpoint.
POST mgmt/cm/global/tasks/device-remove-trust¶
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 task. |
deviceReference | object | True | The deviceReference is a link object for the BIG-IP targeted by this trust removal request. |
link | string | True | URL of deviceReference |
name | string | False | An optional name for the task. |
Query Parameters¶
None
Response¶
The JSON in the body of the POST response can contain the following parameters. The 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.
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
ItemState | object | State of the trust removal task. |
currentStep | string | Current step of the discovery task. Possible values: “INIT”, “VERIFY_DELETE_DEVICE”, “UPDATE_INPROCESS_STATE”, “REMOVE_STATS_AGENT”, “GET_DEVICES_FROM_ALL_GROUPS”, “REMOVE_SHARED_DISCOVERY”, “DELETE_DEVICES_FROM_ALL_GROUPS”, “DELETE_GROUP”, “DELETE_DEVICE_FROM_SILO”, “DELETE_TASKS”, “UNINSTALL_BULK_RPM_ON_BIG_IP”, “DONE”, “FAILED”. |
description | string | An optional description for the task. |
deviceReference | object | The deviceReference is a link object for the BIG-IP targeted by this trust 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 in the collection, used when accessing it directly. |
identityReferences | array | A list of user identities that initiated the task. |
link | string | URL for an user identity |
name | string | An optional name for the task. |
ownerMachineId | string | In a high-availability environment, the machine Id of the host running the task. |
parentTaskReference | object | The task API that initiated the task. |
link | string | URL for the task API that initiated the task. |
selfLink | string | The URL to access this item directly. |
startDateTime | string | The time the task was started. |
status | string | Task status, updated during task. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker. |
username | string | The user that initiated the task. |
userReference | string | The user that initiated the task. |
link | string | URL for userReference |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
GET /cm/global/tasks/device-discovery/<id>¶
To check the status of a task you can send a GET request to the endpoint and specify the task’s id. The 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 task.
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
ItemState | object | State of the trust removal task. |
currentStep | string | Current step of the discovery task. Possible values: “INIT”, “VERIFY_DELETE_DEVICE”, “UPDATE_INPROCESS_STATE”, “REMOVE_STATS_AGENT”, “GET_DEVICES_FROM_ALL_GROUPS”, “REMOVE_SHARED_DISCOVERY”, “DELETE_DEVICES_FROM_ALL_GROUPS”, “DELETE_GROUP”, “DELETE_DEVICE_FROM_SILO”, “DELETE_TASKS”, “UNINSTALL_BULK_RPM_ON_BIG_IP”, “DONE”, “FAILED”. |
description | string | An optional description for the task. |
deviceReference | object | The deviceReference is a link object for the BIG-IP targeted by this trust 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 in the collection, used when accessing it directly. |
identityReferences | array | A list of user identities that initiated the task. |
link | string | URL for an user identity |
name | string | An optional name for the task. |
ownerMachineId | string | In a high-availability environment, the machine Id of the host running the task. |
parentTaskReference | object | The task API that initiated the task. |
link | string | URL for the task API that initiated the task. |
selfLink | string | The URL to access this item directly. |
startDateTime | string | The time the task was started. |
status | string | Task status, updated during task. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker. |
username | string | The user that initiated the task. |
userReference | string | The user that initiated the task. |
link | string | URL for userReference |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
PATCH mgmt/cm/global/tasks/device-remove-trust/<id>¶
To cancel a running task, or restart a task with a “FINISHED” or “FAILED” status, you can send a PATCH request to the endpoint and specify the task’s id. To cancel a running task, send a PATCH request to change the value of status to “CANCEL_REQUESTED”. Then send a GET request to poll the 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 task. To restart a task having a status of “FINISHED” or “FAILED”, send a PATCH request to change the value of status to “STARTED”.
Request Parameters¶
The JSON in the body of the PATCH request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
status | string | True | Standard task status of the task, updated during execution. To cancel the task, this value can be changed to “CANCEL_REQUESTED”. To restart the 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-trust/<id>¶
To delete a task you can send a DELETE request to the endpoint and specify the task’s id. The 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 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 trust relationship of BIG-IP¶
POST https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-trust
The following example creates a task to remove trust relationship of BIG-IP. The JSON in the body of the POST can be similar to the following.
{
"name": "device-remove-trust_10.255.85.115",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/a0f8ab74-0d2f-41d6-ac99-f2e8ae038d75"
}
}
Response¶
The JSON in the response to the POST can look similar to the following. The value of selfLink is the URL for the 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 task’s selfLink.
{
"name": "device-remove-trust_10.255.85.115",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/a0f8ab74-0d2f-41d6-ac99-f2e8ae038d75"
},
"currentStep": "INIT",
"generation": 42,
"lastUpdateMicros": 1566496596746008,
"kind": "cm:global:tasks:device-remove-trust:bigipuntrusttaskstate",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-remove-trust/3e552b0d-1909-421b-9b08-612035cffce0",
"id": "3e552b0d-1909-421b-9b08-612035cffce0",
"status": "STARTED",
"startDateTime": "2019-08-22T16:23:50.250-0400",
"endDateTime": "2019-08-22T16:23:59.592-0400",
"errorMessage": "Cannot remove device theusz-hamtaahk (10.255.85.114) because all services were not removed",
"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 task identified by id and selfLink. You can send repeated GET requests to check the status of the task, which can eventually update to “DONE” and “FINISHED”.
GET https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-trust/<id>
Response¶
The JSON in the response to the GET when the task is done can look similar to the following.
{
"name": "device-remove-trust_10.255.85.115",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/a0f8ab74-0d2f-41d6-ac99-f2e8ae038d75"
},
"currentStep": "INIT",
"generation": 42,
"lastUpdateMicros": 1566496596746008,
"kind": "cm:global:tasks:device-remove-trust:bigipuntrusttaskstate",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-remove-trust/3e552b0d-1909-421b-9b08-612035cffce0",
"id": "3e552b0d-1909-421b-9b08-612035cffce0",
"status": "STARTED",
"startDateTime": "2019-08-22T16:23:50.250-0400",
"endDateTime": "2019-08-22T16:23:59.592-0400",
"errorMessage": "Cannot remove device theusz-hamtaahk (10.255.85.114) because all services were not removed",
"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 task¶
You can send a PATCH request to cancel a running task specified by the task’s id.
PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-trust/<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 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 task.
PATCH to restart a task¶
You can send a PATCH request to restart a task having a status of “FINISHED” or “FAILED”. Specify the task to restart by the task’s id.
PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-trust/<id>
In the body of the PATCH request specify the value of status as “STARTED”.
{
"status": "STARTED"
}
Response¶
You can then send repeated GET requests to poll the task until the value of status updates to “FINISHED” or “FAILED”.
DELETE to delete a discovery task¶
The following example deletes the task identified by id.
DELETE https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-trust/<id>
Response¶
The JSON in the response from a DELETE request is similar to a response from a GET request.