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.