Discovery for Web Application Security (ASM) Management¶
Overview¶
This document describes the use of the Device Discovery and Import Controller task API. This task can discover and import BIG-IP device configurations in the BIG-IQ system. The parameters shown in the examples demonstrate the use of this task to discover the Web Application Security module.
REST Endpoint: /cm/global/tasks/device-discovery-import-controller¶
Requests¶
POST /cm/global/tasks/device-discovery-import-controller¶
Request Parameters¶
Name | Type | Required | Description |
---|---|---|---|
operationalMode | string | False | Specifies whether the new device is being imported or existing devices are being re-imported. |
deviceDetails | array_of_objects | False | List of devices and their import details. |
deviceReference | reference | False | Device reference to re-import already imported device’s configurations. |
link | string | False | URI link of the reference. |
newDevice | object | False | Device details to import a new device. |
address | string | False | IP address of the device to be imported. |
httpsPort | number | False | HTTPS port number to import a new device. |
userName | string | False | User name to authenticate device for import. |
password | string | False | Password to authenticate device for import. |
clusterName | string | False | Name of the HA cluster to which the device belongs. |
useBigiqSync | boolean | False | Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment. |
deployWhenDscChangesPending | boolean | False | Deploy when there are pending DSC changes on BIG-IP. |
moduleList | array_of_objects | False | List of modules to import. |
module | string | False | Module name to import for the device. |
properties | object | False | Additional properties provided for the import.. |
cm:access:import-shared | boolean | False | When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’. |
messages | array_of_objects | False | List of messages gathered during different stages of the device import. |
conflictPolicy | string | False | Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects. |
deviceConflictPolicy | string | False | Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects. |
snapshotWorkingConfig | boolean | False | Snapshot of the working configuration for all devices, before the import. |
accessGroupName | string | False | Access group name to import Access configuration for devices. |
name | string | False | Name of the task. |
errorMessage | string | False | Error message describing details of the task failure. |
description | string | False | Description of the task. |
status | string | False | Current status of task. |
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
operationalMode | string | Specifies whether the new device is being imported or existing devices are being re-imported.. |
deviceDetails | array_of_objects | List of devices and their import details. |
deviceReference | reference | Device reference to re-import already imported device’s configurations. |
link | string | URI link of the reference. |
newDevice | object | Device details to import a new device. |
address | string | IP address of the device to be imported. |
httpsPort | number | HTTPS port number to import a new device. |
userName | string | User name to authenticate device for import. |
password | string | Password to authenticate device for import. |
clusterName | string | Name of the HA cluster to which the device belongs. |
useBigiqSync | boolean | Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment. |
deployWhenDscChangesPending | boolean | Deploy when there are pending DSC changes on BIG-IP. |
moduleList | array_of_objects | List of modules to import. |
module | string | Module name to import for the device. |
status | string | Device import status. |
errorMsg | string | Error message if device import failed. |
startTime | string | Start time of module import for the device. |
endTime | string | End time of module import for the device. |
properties | object | Additional properties provided for the import.. |
cm:access:import-shared | boolean | When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’. |
taskReference | reference | Task reference. |
link | string | URI link of the reference. |
snapshotWorkingConfig | boolean | Snapshot module’s working configuration before import. |
deviceStatus | string | Import status of the device. |
trustTaskReference | reference | Device trust establishment task reference. |
link | string | URI link of the reference. |
superDiscoveryTaskReference | reference | Config discovery task reference. |
link | string | URI link of the reference. |
superImportTaskReference | reference | Configuration import task reference. |
link | string | URI link of the reference. |
messages | array_of_objects | List of messages gathered during different stages of the device import. |
msgType | string | Message severity level. |
msg | string | Message details. |
conflictPolicy | string | Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects. |
deviceConflictPolicy | string | Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects. |
snapshotWorkingConfig | boolean | Snapshot of the working configuration for all devices, before the import. |
accessGroupName | string | Access group name to import Access configuration for devices. |
currentStep | string | Current import step. |
startDateTime | string | Start date and time of task. |
name | string | Name of the task. |
errorMessage | string | Error message describing details of the task failure. |
description | string | Description of the task. |
endDateTime | string | End date and time of task. |
status | string | Current status of task. |
Error Response¶
HTTP/1.1 400 Bad Request
This response status is related to an error during a POST method. A detailed error message displays in the response.
HTTP/1.1 401 Unauthorized
This response occurs when access is denied due to invalid credentials or insufficient permissions.
Permissions¶
Role | Allow |
---|---|
Trust_Discovery_Import | Yes |
Device_Viewer | No |
device_manager | No |
GET /cm/global/tasks/device-discovery-import-controller/<id>¶
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
operationalMode | string | Specifies whether the new device is being imported or existing devices are being re-imported.. |
deviceDetails | array_of_objects | List of devices and their import details. |
deviceReference | reference | Device reference to re-import already imported device’s configurations. |
link | string | URI link of the reference. |
newDevice | object | Device details to import a new device. |
address | string | IP address of the device to be imported. |
httpsPort | number | HTTPS port number to import a new device. |
userName | string | User name to authenticate device for import. |
password | string | Password to authenticate device for import. |
clusterName | string | Name of the HA cluster to which the device belongs. |
useBigiqSync | boolean | Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment. |
deployWhenDscChangesPending | boolean | Deploy when there are pending DSC changes on BIG-IP. |
moduleList | array_of_objects | List of modules to import. |
module | string | Module name to import for the device. |
status | string | Device import status. |
errorMsg | string | Error message if device import failed. |
startTime | string | Start time of module import for the device. |
endTime | string | End time of module import for the device. |
properties | object | Additional properties provided for the import.. |
cm:access:import-shared | boolean | When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’. |
taskReference | reference | Task reference. |
link | string | URI link of the reference. |
snapshotWorkingConfig | boolean | Snapshot module’s working configuration before import. |
deviceStatus | string | Import status of the device. |
trustTaskReference | reference | Device trust establishment task reference. |
link | string | URI link of the reference. |
superDiscoveryTaskReference | reference | Config discovery task reference. |
link | string | URI link of the reference. |
superImportTaskReference | reference | Configuration import task reference. |
link | string | URI link of the reference. |
messages | array_of_objects | List of messages gathered during different stages of the device import. |
msgType | string | Message severity level. |
msg | string | Message details. |
conflictPolicy | string | Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects. |
deviceConflictPolicy | string | Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects. |
snapshotWorkingConfig | boolean | Snapshot of the working configuration for all devices, before the import. |
accessGroupName | string | Access group name to import Access configuration for devices. |
currentStep | string | Current import step. |
startDateTime | string | Start date and time of task. |
name | string | Name of the task. |
errorMessage | string | Error message describing details of the task failure. |
description | string | Description of the task. |
endDateTime | string | End date and time of task. |
status | string | Current status of task. |
Error Response¶
HTTP/1.1 400 Bad Request
This response status is related to an error during a GET method. A detailed error message displays in the response.
HTTP/1.1 401 Unauthorized
This response occurs when access is denied due to invalid credentials or insufficient permissions.
Permissions¶
Role | Allow |
---|---|
Trust_Discovery_Import | Yes |
Device_Viewer | Yes |
device_manager | Yes |
DELETE /cm/global/tasks/device-discovery-import-controller/<id>¶
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
operationalMode | string | Specifies whether the new device is being imported or existing devices are being re-imported.. |
deviceDetails | array_of_objects | List of devices and their import details. |
deviceReference | reference | Device reference to re-import already imported device’s configurations. |
link | string | URI link of the reference. |
newDevice | object | Device details to import a new device. |
address | string | IP address of the device to be imported. |
httpsPort | number | HTTPS port number to import a new device. |
userName | string | User name to authenticate device for import. |
password | string | Password to authenticate device for import. |
clusterName | string | Name of the HA cluster to which the device belongs. |
useBigiqSync | boolean | Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment. |
deployWhenDscChangesPending | boolean | Deploy when there are pending DSC changes on BIG-IP. |
moduleList | array_of_objects | List of modules to import. |
module | string | Module name to import for the device. |
status | string | Device import status. |
errorMsg | string | Error message if device import failed. |
startTime | string | Start time of module import for the device. |
endTime | string | End time of module import for the device. |
properties | object | Additional properties provided for the import.. |
cm:access:import-shared | boolean | When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’. |
taskReference | reference | Task reference. |
link | string | URI link of the reference. |
snapshotWorkingConfig | boolean | Snapshot module’s working configuration before import. |
deviceStatus | string | Import status of the device. |
trustTaskReference | reference | Device trust establishment task reference. |
link | string | URI link of the reference. |
superDiscoveryTaskReference | reference | Config discovery task reference. |
link | string | URI link of the reference. |
superImportTaskReference | reference | Configuration import task reference. |
link | string | URI link of the reference. |
messages | array_of_objects | List of messages gathered during different stages of the device import. |
msgType | string | Message severity level. |
msg | string | Message details. |
conflictPolicy | string | Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects. |
deviceConflictPolicy | string | Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects. |
snapshotWorkingConfig | boolean | Snapshot of the working configuration for all devices, before the import. |
accessGroupName | string | Access group name to import Access configuration for devices. |
currentStep | string | Current import step. |
startDateTime | string | Start date and time of task. |
name | string | Name of the task. |
errorMessage | string | Error message describing details of the task failure. |
description | string | Description of the task. |
endDateTime | string | End date and time of task. |
status | string | Current status of task. |
Error Response¶
HTTP/1.1 400 Bad Request
This response status is related to an error during a DELETE method. A detailed error message displays in the response.
HTTP/1.1 401 Unauthorized
This response occurs when access is denied due to invalid credentials or insufficient permissions.
Permissions¶
Role | Allow |
---|---|
Trust_Discovery_Import | Yes |
Device_Viewer | No |
device_manager | No |
Examples¶
Create Device Discovery and Import Task¶
POST /cm/global/tasks/device-discovery-import-controller
{
"operationalMode": "NEW_DEVICE",
"deviceDetails": [{
"newDevice": {
"address": "10.241.102.232",
"httpsPort": 443,
"userName": "admin",
"password": "admin"
},
"moduleList": [
{
"module": "adc_core"
},
{
"module": "asm"
},
{
"module": "security_shared"
}],
"messages": [{
}]
}],
"conflictPolicy": "USE_BIGIP",
"deviceConflictPolicy": "USE_BIGIP",
"snapshotWorkingConfig": true,
"name": "task_for_xyz",
"description": "This task is to accomplish xyz."
}
Response¶
HTTP/1.1 200 OK
{
"operationalMode": "NEW_DEVICE",
"deviceDetails": [
{
"newDevice": {
"address": "10.241.102.232",
"httpsPort": 443,
"userName": "admin",
"password": "39wEC7+dnG9BKlkuQl671toNDTvRuK/4L4CwVpgR4Qc="
},
"moduleList": [
{
"module": "adc_core"
},
{
"module": "asm"
},
{
"module": "security_shared"
}
],
"messages": [
{}
]
}
],
"conflictPolicy": "USE_BIGIP",
"deviceConflictPolicy": "USE_BIGIP",
"snapshotWorkingConfig": true,
"id": "a83d1e27-98d5-467f-bba5-d1bfe34d52cd",
"status": "STARTED",
"name": "task_for_xyz",
"description": "This task is to accomplish xyz.",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [
{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}
],
"ownerMachineId": "bdbd9f5b-9df1-4630-a743-d692b4d523d9",
"taskWorkerGeneration": 1,
"generation": 1,
"lastUpdateMicros": 1524472514307620,
"kind": "cm:global:tasks:device-discovery-import-controller:discoveryandimportcontrollertaskitemstate",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/a83d1e27-98d5-467f-bba5-d1bfe34d52cd"
}
Get Device Discovery and Import Task¶
GET /cm/global/tasks/device-discovery-import-controller/<id>
Response¶
HTTP/1.1 200 OK
{
"operationalMode": "NEW_DEVICE | EXISTING_DEVICE",
"deviceDetails": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
},
"newDevice": {
"address": "11.111.111.111",
"httpsPort": 443,
"userName": "admin",
"password": "password",
"clusterName": "cluster_1_data_center_1",
"useBigiqSync": false,
"deployWhenDscChangesPending": false
},
"moduleList": [{
"module": "adc_core",
"status": "STARTED",
"errorMsg": "Failed importing adc_core for device 11.111.111.111. Something bad happened.",
"startTime": "2018-01-30T21:37:10.104-0800",
"endTime": "2018-01-30T21:38:07.104-0800",
"properties": {
"cmAccessImportShared": true
},
"taskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
},
"snapshotWorkingConfig": true
}],
"deviceStatus": "IMPORT_STAGE",
"trustTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
},
"superDiscoveryTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
},
"superImportTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
},
"messages": [{
"msgType": "INFO",
"msg": "Importing adc_core for device 11.111.111.111."
}]
}],
"conflictPolicy": "USE_BIGIP",
"deviceConflictPolicy": "USE_BIGIP",
"snapshotWorkingConfig": true,
"accessGroupName": "DataCenter_1_AccessGroup",
"currentStep": "IMPORT_DEVICES",
"startDateTime": "2018-02-01T19:44:17.804-0800",
"name": "task_for_xyz",
"errorMessage": "Something bad happened at step 5.",
"description": "This task is to accomplish xyz.",
"endDateTime": "2018-02-01T19:44:17.804-0800",
"status": "STARTED"
}
Delete Device Discovery and Import Task¶
DELETE /cm/global/tasks/device-discovery-import-controller/<id>
Response¶
HTTP/1.1 200 OK
{
"conflictPolicy": "USE_BIGIP",
"currentStep": "DONE",
"description": "This task is to accomplish xyz.",
"deviceConflictPolicy": "USE_BIGIP",
"deviceDetails": [
{
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/e9339a51-8d01-4c6e-bf6a-be2f850c0f62"
},
"newDevice": {
"address": "10.241.102.232",
"httpsPort": 443,
"userName": "admin",
"password": "39wEC7+dnG9BKlkuQl671toNDTvRuK/4L4CwVpgR4Qc="
},
"moduleList": [
{
"module": "adc_core"
},
{
"module": "security_shared"
},
{
"module": "asm"
}
],
"deviceStatus": "FINISHED",
"trustTaskReference": {
"link": "https://localhost/mgmt/cm/global/tasks/device-trust/455b9c49-938b-4d63-9bf1-6cc6e69dbf40"
},
"superDiscoveryTaskReference": {
"link": "https://localhost/mgmt/cm/global/tasks/device-discovery/c2d324ce-21a1-4db1-a652-670133528bc3"
},
"superImportTaskReference": {
"link": "https://localhost/mgmt/cm/global/tasks/device-import/e09aa0f2-524d-4e47-bfca-33c87a40ca5d"
}
}
],
"endDateTime": "2018-04-23T01:37:32.887-0700",
"generation": 10,
"id": "a83d1e27-98d5-467f-bba5-d1bfe34d52cd",
"identityReferences": [
{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}
],
"kind": "cm:global:tasks:device-discovery-import-controller:discoveryandimportcontrollertaskitemstate",
"lastUpdateMicros": 1524472652938156,
"name": "task_for_xyz",
"operationalMode": "NEW_DEVICE",
"ownerMachineId": "bdbd9f5b-9df1-4630-a743-d692b4d523d9",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/a83d1e27-98d5-467f-bba5-d1bfe34d52cd",
"snapshotWorkingConfig": true,
"startDateTime": "2018-04-23T01:35:14.324-0700",
"status": "FINISHED",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"username": "admin"
}