Device Discovery

Overview

Use the Device Discovery API to create a super-task to determine what module objects exist on a specific 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’. To discover multiple modules from a single BIG-IP, send a POST request to the device-discovery task collection on the BIG-IQ. Specify the modules of interest 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 discover the specified modules. 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 RMA API to remove module objects from the working-config of the BIG-IQ.

REST Endpoint: mgmt/cm/global/tasks/device-discovery

Requests

To create a super-task to determine what module objects exist on a single BIG-IP and create corresponding copies of these module objects in the BIG-IQ’s current-config, send a POST request to the device-discovery endpoint.

POST mgmt/cm/global/tasks/device-discovery

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 deviceReference is a link object for the BIG-IP targeted by this discovery request.
     link string True URL of deviceReference
moduleList object array True A list identifying the module objects to discover. The status fields of the module objects are not required in the POST request. Provide the module object identifier in module.
     module string True Module object 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 discovery task.
     allModuleStatus object List of discovered modules and status, whether being discovered in this run or previously discovered. Format is the same as moduleList.
     currentConfigConsistencyCheckReference object Reference to the current-config consistency-check task run by discovery.
          link string URL of currentConfigConsistencyCheckReference
     currentStep string Current step of the discovery task. Possible values: “INIT”, “CHECK_BULK_RPM_SUPPORT”, “INSTALL_BULK_RPM_ON_BIG_IP”, “FIND_OR_CREATE_MODULE_GROUPS”, “FIND_OR_CREATE_DEVICE_IN_MODULE_GROUPS”, “CHECK_RUNNING_TASKS”, “PROCESS_MODULE_TASKS”, “FAILED” or “DONE”.
     description string An optional description for the super-task.
     deviceReference string The value of deviceReference is a link object for the BIG-IP targeted by this discovery request.
          link string URL of deviceReference
     endDateTime string The time the super-task stopped running.
     errorMessage string An error encountered while the super-task was running. There can be errors even when the task’s status is not “FAILED”.
     id string The id of the super-task.
     moduleList object List of modules being discovered, with status.
          endTime string End time for module processing (UTC).
          errorMsg string Error message from module discovery 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 discovery task was already active.
          taskReference string Reference to module discovery task.
          link string URL of the reference to module discovery task.
     name string An optional name for the super-task.
     ownerMachineId string In a high-availability environment, the machine Id of the host running the super-task.
     selfLink string The URL to access this item directly.
     startDateTime string The time the super-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 super-task.
          link string URL for userReference
     identityReferences array A list of user identities that initiated the super-task.
          link string URL for an user identity
     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 super-task.

Permissions

Role Allow
admin Yes

GET /cm/global/tasks/device-discovery/<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 discovery task.
     allModuleStatus object List of discovered modules and status, whether being discovered in this run or previously discovered. Format is the same as moduleList.
     currentConfigConsistencyCheckReference object Reference to the current-config consistency-check task run by discovery.
          link string URL of currentConfigConsistencyCheckReference
     currentStep string Current step of the discovery task. Possible values: “INIT”, “CHECK_BULK_RPM_SUPPORT”, “INSTALL_BULK_RPM_ON_BIG_IP”, “FIND_OR_CREATE_MODULE_GROUPS”, “FIND_OR_CREATE_DEVICE_IN_MODULE_GROUPS”, “CHECK_RUNNING_TASKS”, “PROCESS_MODULE_TASKS”, “FAILED” or “DONE”.
     description string An optional description for the super-task.
     deviceReference string The value of deviceReference is a link object for the BIG-IP targeted by this discovery request.
          link string URL of deviceReference
     endDateTime string The time the super-task stopped running.
     errorMessage string An error encountered while the super-task was running. There can be errors even when the task’s status is not “FAILED”.
     id string The id of the super-task.
     moduleList object List of modules being discovered, with status.
          endTime string End time for module processing (UTC).
          errorMsg string Error message from module discovery 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 discovery task was already active.
          taskReference string Reference to module discovery task.
          link string URL of the reference to module discovery task.
     name string An optional name for the super-task.
     ownerMachineId string In a high-availability environment, the machine Id of the host running the super-task.
     selfLink string The URL to access this item directly.
     startDateTime string The time the super-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 super-task.
          link string URL for userReference
     identityReferences array A list of user identities that initiated the super-task.
          link string URL for an user identity
     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-discovery/<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 discovered by changing moduleList.
     module string False 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-discovery/<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 discover multiple modules

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

The following example creates a super-task to discover a module on the specified BIG-IP and create a corresponding copy of the specified module object in the BIG-IQ’s current-config. The JSON in the body of the POST can be similar to the following.

{
    "name": "discovery_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": "discovery_10.255.85.114",
    "description": null,
    "deviceReference": {
            "link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
    },
    "currentStep": "INIT",
    "currentConfigConsistencyCheckReference": {
            "link": "https://localhost/mgmt/cm/global/tasks/current-config-consistency-check/6870028a-73a1-48d8-8b98-d408f1e13d6e"
    },
    "moduleList": [{
            "module": "firewall",
            "status": "STARTED",
            "errorMsg": "Task https://localhost/mgmt/cm/firewall/tasks/discover-config/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/adc-core/tasks/discover-config/f5b4bb89-f6c6-400a-a24d-c6ee6db5138f"
            }
    }],
    "allModuleStatus": [{}],
    "generation": 42,
    "lastUpdateMicros": 1566831675472009,
    "kind": "cm:global:tasks:device-discovery:discoverysupertaskitemstate",
    "selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery/5c666846-e283-41cf-96f8-4b2e32360048",
    "id": "5c666846-e283-41cf-96f8-4b2e32360048",
    "status": "STARTED",
    "startDateTime": "2019-08-28T09:38:25.097-0400",
    "endDateTime": "2019-08-28T09:38:44.608-0400",
    "errorMessage": "Failed to find or create module groups",
    "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 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-discovery/<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": "discovery_10.255.85.114",
    "description": null,
    "deviceReference": {
            "link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
    },
    "currentStep": "INIT",
    "currentConfigConsistencyCheckReference": {
            "link": "https://localhost/mgmt/cm/global/tasks/current-config-consistency-check/6870028a-73a1-48d8-8b98-d408f1e13d6e"
    },
    "moduleList": [{
            "module": "firewall",
            "status": "FINISHED",
            "errorMsg": "Task https://localhost/mgmt/cm/firewall/tasks/discover-config/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/adc-core/tasks/discover-config/f5b4bb89-f6c6-400a-a24d-c6ee6db5138f"
            }
    }],
    "allModuleStatus": [{}],
    "generation": 42,
    "lastUpdateMicros": 1566831675472009,
    "kind": "cm:global:tasks:device-discovery:discoverysupertaskitemstate",
    "selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery/5c666846-e283-41cf-96f8-4b2e32360048",
    "id": "5c666846-e283-41cf-96f8-4b2e32360048",
    "status": "FINISHED",
    "startDateTime": "2019-08-28T09:38:25.097-0400",
    "endDateTime": "2019-08-28T09:38:44.608-0400",
    "errorMessage": "Failed to find or create module groups",
    "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 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-discovery/<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-discovery/<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 discovery task

The following example deletes the super-task identified by id.

DELETE https://<BIG-IQ>/mgmt/cm/global/tasks/device-discovery/<id>

Response

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