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.

Previous Next