Device Establish Trust¶

Overview¶

Use the Device Establish Trust API to establish a trust relationship between BIG-IQ and a BIG-IP. Trust establishment is the first step taken when adding a device to BIG-IQ management control. Admin-level credentials (username and password) must be provided to the task to have access to the BIG-IP. These credentials are not retained beyond task completion. The trust relationship enables future management operations to run without explicitly providing the BIG-IP’s username and password. The trusted BIG-IP can then have modules or services imported or discovered. Use the Device Remove Trust API to remove a trust relationship between BIG-IQ and a BIG-IP.

Use the Device Discovery API to create a super-task to determine what module objects exist on a specific trusted BIG-IP and then create corresponding copies of these module objects in the BIG-IQ’s current-config. This process is referred to as ‘discovery’.

REST Endpoint: mgmt/cm/global/tasks/device-trust¶

Requests¶

To create a task to establish a trust relationship between BIG-IQ and a BIG-IP, send a POST request to the device-trust endpoint.

POST mgmt/cm/global/tasks/device-trust¶

Request Parameters¶

The JSON in the body of the POST request can include the following parameters.

Name	Type	Required	Description
address	string	True	IP address of the BIG-IP.
checkMinSupportedBigIpVersion	boolean	True	If true, reject this BIG-IP if it reports less than the minimum supported version number. Even if false, BIG-IQ will still reject BIG-IPs earlier than V11.5.0.
clusterName	string	False	Cluster name, if device to be added into cluster.
deployWhenDscChangesPending	boolean	False	Deploy cluster even if cluster has not been synchronized.
description	string	False	An optional description for the task.
httpsPort	number	False	TCP port number for HTTPS service on BIG-IP. Default value is 443.
name	string	False	An optional name for the task.
password	string	True	Password of specified BIG-IP user name.
silo	string	False	Configuration silo for this device. This null for default configuration.
useBigiqSync	boolean	False	Cluster: use BIG-IQ sync for cluster members.
userName	string	True	BIG-IP user name to use for trust establishment.

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 establishment task.
address	string	IP address of the BIG-IP.
bigipClusterMgmtTaskReference	object	Cluster management task created by this task.
link	string	URL for an cluster management task
checkMinSupportedBigIpVersion	boolean	If true, reject this BIG-IP if it reports less than the minimum supported version number. Even if false, BIG-IQ will still reject BIG-IPs earlier than V11.5.0.
clusterName	string	Cluster name, if device to be added into cluster.
confirmFrameworkUpgrade	boolean	Client confirms framework update assent.
currentStep	string	Current step of the discovery task. Possible values: “INIT”, “CHECK_IF_TRUSTED”, “GET_NUMBER_MANAGED_BIGIPS”, “CHECK_BIGIP_LICENSE”, “CHECK_BIGIP_CLUSTER_SIZE”, “CHECK_BIGIP_AVAILABLE”, “POST_FRAMEWORK_INFO”, “PENDING_FRAMEWORK_UPGRADE_CONFIRMATION”, “POST_DEVICE_BIGIP_GROUP”, “POST_DEVICE_BIGIP_TRUST_GROUP”, “DISCOVER_SHARED_CONFIG”, “ADD_DEVICE_TO_SILO”, “START_CLUSTER_MGMT_TASK”, “WAIT_FOR_CLUSTER_MGMT_TASK”, “DONE” or “FAILED”.
description	string	An optional description for the task.
deployWhenDscChangesPending	boolean	Deploy cluster even if cluster has not been synchronized.
discoveryTaskReference	object	Shared discovery task started by this trust task.
link	string	URL of discoveryTaskReference
endDateTime	string	The time the task stopped running.
errorType	string	Classification of error being reported on task failure. Possible values: DEVICE_ALREADY_TRUSTED.
errorMessage	string	An error encountered while the task was running. There may be errors even when the task is not FAILED.
httpsPort	number	TCP port number for HTTPS service on BIG-IP. Default value is 443.
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
ignoreFrameworkUpgrade	boolean	Client says skip upgrade of REST framework on BIG-IP.
machineId	string	The returned machine id for the device.
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.
password	string	Password of specified BIG-IP user name.
requireFrameworkUpgrade	string	Indicates to client that REST framework update is required on this device.
requireRootCredential	boolean	Indicates to client that root credentials are required.
rootPassword	string	Password of root user on BIG-IP.
rootUser	string	Password of root user on BIG-IP.
rootUserValidationMessage	string	Error message from root user/password validation failure.
selfLink	string	The URL to access this item directly.
silo	string	Configuration silo for this device. This null for default configuration.
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.
useBigiqSync	boolean	Use BIG-IQ sync for cluster members.
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-trust/<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.
address	string	IP address of the BIG-IP.
bigipClusterMgmtTaskReference	object	Cluster management task created by this task.
link	string	URL for an cluster management task
checkMinSupportedBigIpVersion	boolean	If true, reject this BIG-IP if it reports less than the minimum supported version number. Even if false, BIG-IQ will still reject BIG-IPs earlier than V11.5.0.
clusterName	string	Cluster name, if device to be added into cluster.
confirmFrameworkUpgrade	boolean	Client confirms framework update assent.
currentStep	string	Current step of the discovery task. Possible values: “INIT”, “CHECK_IF_TRUSTED”, “GET_NUMBER_MANAGED_BIGIPS”, “CHECK_BIGIP_LICENSE”, “CHECK_BIGIP_CLUSTER_SIZE”, “CHECK_BIGIP_AVAILABLE”, “POST_FRAMEWORK_INFO”, “PENDING_FRAMEWORK_UPGRADE_CONFIRMATION”, “POST_DEVICE_BIGIP_GROUP”, “POST_DEVICE_BIGIP_TRUST_GROUP”, “DISCOVER_SHARED_CONFIG”, “ADD_DEVICE_TO_SILO”, “START_CLUSTER_MGMT_TASK”, “WAIT_FOR_CLUSTER_MGMT_TASK”, “DONE” or “FAILED”.
description	string	An optional description for the task.
deployWhenDscChangesPending	boolean	Deploy cluster even if cluster has not been synchronized.
discoveryTaskReference	object	Shared discovery task started by this trust task.
link	string	URL of discoveryTaskReference
endDateTime	string	The time the task stopped running.
errorType	string	Classification of error being reported on task failure. Possible values: DEVICE_ALREADY_TRUSTED.
errorMessage	string	An error encountered while the task was running. There may be errors even when the task is not FAILED.
httpsPort	number	TCP port number for HTTPS service on BIG-IP. Default value is 443.
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
ignoreFrameworkUpgrade	boolean	Client says skip upgrade of REST framework on BIG-IP.
machineId	string	The returned machine id for the device.
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.
password	string	Password of specified BIG-IP user name.
requireFrameworkUpgrade	string	Indicates to client that REST framework update is required on this device.
requireRootCredential	boolean	Indicates to client that root credentials are required.
rootPassword	string	Password of root user on BIG-IP.
rootUser	string	Password of root user on BIG-IP.
rootUserValidationMessage	string	Error message from root user/password validation failure.
selfLink	string	The URL to access this item directly.
silo	string	Configuration silo for this device. This null for default configuration.
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.
useBigiqSync	boolean	Use BIG-IQ sync for cluster members.
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-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-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 establish trust relationship of BIG-IP¶

POST https://<BIG-IQ>/mgmt/cm/global/tasks/device-trust

The following example creates a task to establish trust relationship of BIG-IP. The JSON in the body of the POST can be similar to the following.

{
    "name": "trust_10.255.85.115",
    "description": null,
    "address": "10.255.85.115",
    "httpsPort": 443,
    "userName": "admin",
    "password": "testpassword",
    "clusterName": "",
    "useBigiqSync": false,
    "deployWhenDscChangesPending": false,
    "silo": null,
    "checkMinSupportedBigIpVersion": true
}

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": "trust_10.255.85.115",
    "description": null,
    "address": "10.255.85.115",
    "httpsPort": 443,
    "userName": "admin",
    "password": "testpassword",
    "clusterName": "",
    "useBigiqSync": false,
    "deployWhenDscChangesPending": false,
    "silo": null,
    "checkMinSupportedBigIpVersion": true,
    "requireFrameworkUpgrade": false,
    "requireRootCredential": false,
    "confirmFrameworkUpgrade": true,
    "ignoreFrameworkUpgrade": true,
    "rootUser": "root",
    "rootPassword": "default",
    "machineId": "a0f8ab74-0d2f-41d6-ac99-f2e8ae038d75",
    "isChassisDevice": false,
    "bigipClusterMgmtTaskReference": {
            "link": "https://localhost/mgmt/cm/global/tasks/bigip-cluster-mgmt/54436fe8-94a2-943f-5eb1-195655719aef"
    },
    "discoveryTaskReference": {
            "link": "https://localhost/mgmt/cm/shared/tasks/discover-config/93eaebdb-eae3-4061-aebc-d46e1574ba2a"
    },
    "errorType": "DEVICE_ALREADY_TRUSTED",
    "currentStep": "INIT",
    "rootUserValidationMessage": "Failed to connect to device 10.255.85.115 as root: permission denied",
    "generation": 42,
    "lastUpdateMicros": 1566496582117009,
    "kind": "cm:global:tasks:device-trust:bigiptrusttaskstate",
    "selfLink": "https://localhost/mgmt/cm/global/tasks/device-trust/1e39c808-f271-42f2-bc54-ced7c989e36b",
    "id": "1e39c808-f271-42f2-bc54-ced7c989e36b",
    "status": "STARTED",
    "startDateTime": "2019-08-22T13:26:39.045-0400",
    "endDateTime": "2019-08-22T13:26:48.174-0400",
    "errorMessage": "Failed to connect to device 10.255.85.116 using address 10.255.85.116 and port 443: No route to host (Host unreachable)",
    "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": {
            "link": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/7e853383-4e8a-4e4b-93d8-7f117195223c"
    }
}

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-trust/<id>

Response¶

The JSON in the response to the GET when the task is done can look similar to the following.

{
    "name": "trust_10.255.85.115",
    "description": null,
    "address": "10.255.85.115",
    "httpsPort": 443,
    "userName": "admin",
    "password": "testpassword",
    "clusterName": "",
    "useBigiqSync": false,
    "deployWhenDscChangesPending": false,
    "silo": null,
    "checkMinSupportedBigIpVersion": true,
    "requireFrameworkUpgrade": false,
    "requireRootCredential": false,
    "confirmFrameworkUpgrade": true,
    "ignoreFrameworkUpgrade": true,
    "rootUser": "root",
    "rootPassword": "default",
    "machineId": "a0f8ab74-0d2f-41d6-ac99-f2e8ae038d75",
    "isChassisDevice": false,
    "bigipClusterMgmtTaskReference": {
            "link": "https://localhost/mgmt/cm/global/tasks/bigip-cluster-mgmt/54436fe8-94a2-943f-5eb1-195655719aef"
    },
    "discoveryTaskReference": {
            "link": "https://localhost/mgmt/cm/shared/tasks/discover-config/93eaebdb-eae3-4061-aebc-d46e1574ba2a"
    },
    "errorType": "DEVICE_ALREADY_TRUSTED",
    "currentStep": "INIT",
    "rootUserValidationMessage": "Failed to connect to device 10.255.85.115 as root: permission denied",
    "generation": 42,
    "lastUpdateMicros": 1566496582117009,
    "kind": "cm:global:tasks:device-trust:bigiptrusttaskstate",
    "selfLink": "https://localhost/mgmt/cm/global/tasks/device-trust/1e39c808-f271-42f2-bc54-ced7c989e36b",
    "id": "1e39c808-f271-42f2-bc54-ced7c989e36b",
    "status": "STARTED",
    "startDateTime": "2019-08-22T13:26:39.045-0400",
    "endDateTime": "2019-08-22T13:26:48.174-0400",
    "errorMessage": "Failed to connect to device 10.255.85.116 using address 10.255.85.116 and port 443: No route to host (Host unreachable)",
    "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": {
            "link": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/7e853383-4e8a-4e4b-93d8-7f117195223c"
    }
}

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-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-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-trust/<id>

Response¶

The JSON in the response from a DELETE request is similar to a response from a GET request.

Previous Next