Configuration Restore¶
Overview¶
Use the Configuration Restore API to create a task to restore a specific module object in the BIG-IQ’s working-config to a previous snapshot. Separate tasks are required to restore the configurations of different modules (i.e. access, adc-core, asm, dns, firewall, security-shared or websafe) to their snapshots. Use the Configuration Snapshot API to create a snapshot of the working configuration maintained and edited on the BIG-IQ. A snapshot can record the state of the working-config objects for a specified module even when those objects are subsequently modified or deleted. To revert configuration changes on BIG-IP, you must deploy the restored working-config on the BIG-IQ to the BIG-IP using the Configuration Deployment API. The Configuration Deployment API can create a deployment task which can update the configuration of a module on multiple BIG-IPs to match the working-config of the BIG-IQ.
You can evaluate the differences between a snapshot and the current working-config before restoring the BIG-IQ. This may speed a restore because objects without differences need not be restored. To evaluate differences only, set skipRestore to true when initially posting the restore task. The task will suspend with status “FINISHED” and a currentStep of “PENDING_CONFIRMATION” before restoring the BIG-IQ. To complete the restore, the you can then PATCH the task’s status to “STARTED” and skipRestore to false to resume execution. If the restore task is posted with skipRestore false or omitted, then it will not suspend in the “PENDING_CONFIRMATION” step.
REST Endpoint: mgmt/cm/<module>/tasks/restore-config¶
Requests¶
To start a new restore task, send a POST request to the <module>/tasks/restore-config endpoint. The placeholder text <module> represents the module being restored. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
POST mgmt/cm/<module>/tasks/restore-config¶
Request Parameters¶
The JSON in the body of the POST request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
coordinationTaskId | string | False | An existing coordination id that the restore task should use. |
description | string | False | Optional description for task |
name | string | True | Name for the task |
objectReferences | array | False | Indicates partial or selective restore. References to objects in the config to use as starting points for configuration enumeration. |
link | string | True | URL of the object |
siloFilter | string | False | Restricts the restore to one silo. Input for full restore, output for partial restore. |
skipRestore | boolean | False | True means this is an evaluation of the differences without a restore. The task can optionally be resumed after inspection. |
skipVerifyConfig | boolean | False | If true, do not run verification after restore. |
snapshotReference | object | True | The snapshot from which objects are to be restored. |
link | string | True | URL of the snapshot |
snapshotWorkingConfig | boolean | False | Make a new snapshot of working-config before actual restore. |
specifiedObjectsOnly | boolean | False | In partial mode, do not follow reference chains. Use of this requires knowledge that the result will be useful. |
Query Parameters¶
None
Response¶
The JSON in the body of the response to the POST request represents the initial state of the restore task and includes a selfLink and id for the task. The task’s status in the initial response to the POST request can be “STARTED”. To poll for an updated status of the task you can send GET requests to the task’s selfLink.
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
clusterSyncTaskReferences | array | List of references to cluster-sync tasks created by this restore task. |
link | string | URL of the cluster-sync task |
configCopyTaskReference | object | Reference to the config-copy task created by this restore task. |
link | string | URL of the config-copy task task |
coordinationOpCount | number | Count of coordination operations sent by this restore task. |
coordinationTaskId | string | An existing coordination id that the restore task should use. |
createdSnapshotTaskReference | object | Reference to the snapshot task created by this restore task. |
link | string | URL of the snapshot task |
currentStep | string | Indicates what the task is currently doing. Possible values: “INIT”, “CHECK_FOR_RUNNING_TASKS”, “GET_SNAPSHOT”, “START_CHILD_TASK_EVAL”, “CHECK_CLUSTERS”, “VALIDATE_SILO”, “CREATE_DIFFERENCE”, “VERIFY_DIFFERENCE”, “WAIT_FOR_CHILD_TASK_EVAL”, “PENDING_CONFIRMATION”, “CREATE_SNAPSHOT”, “START_COORDINATION”, “START_CHILD_TASKS_COPY_CONFIG”, “COPY_CONFIG”, “SETUP_LSO”, “GET_CLUSTER_GROUPS”, “SYNC_CLUSTER_GROUPS”, “WAIT_FOR_START_CHILD_TASKS_COPY_CONFIG”, “PRE_COMMIT”, “COMMIT_COORDINATION”, “PENDING_VERIFY_CONFIG”, “START_CHILD_TASK_VERIFY_CONFIG”, “VERIFY_CONFIG”, “WAIT_FOR_CHILD_TASK_VERIFY_CONFIG” or “DONE”. |
description | string | Optional description for task |
deviceDetails | array | Tracks restore details, not necessarily device-related. Shared objects if deviceReference and deviceGroupReference are both null. |
currentSilo | string | The silo containing the device or device-group in the live system. |
deviceGroupReference | object | Device-group reference, for device-group-specific config items. |
link | string | The URL of device group |
deviceReference | object | Device reference, for device-specific config items. |
link | string | The URL of the device. |
hostname | number | Host name for device. |
notFound | boolean | Device or device-group does not exist; restore skipped. |
siloChanged | boolean | Device or device-group has been moved to a different silo since snapshot was taken. |
verificationCriticalErrorCount | number | Critical error count from verification task. |
verificationErrorCount | number | Non-critical error count from verification task. |
deviceGroupReference | object | Access only; device-group reference from the snapshot. |
link | string | URL of the device group |
differenceReference | object | Reference to the difference result created by the differencer task. |
link | string | URL of the difference result |
differenceTaskReference | object | Reference to the differencer task created by this restore task. |
link | string | URL of the device group |
endDateTime | string | The time the task ended. |
errorMessage | string | An error encountered while the task was running. There may be errors even when the task is not “FAILED”. |
id | string | The id for the item in the collection, used when accessing it directly. |
identityReferences | array | A list of user identities that initiated the task |
link | string | The URL of the identity. |
name | string | Name for the task |
noDifferenceFound | boolean | Copy of noDifferenceFound flag from the difference result (for client convenience). |
objectReferences | array | Indicates partial or selective restore. References to objects in the config to use as starting points for configuration enumeration. |
link | string | URL of the object |
ownerMachineId | string | In a high-availability environment, the machineId of the host running the task |
parentTaskReference | object | The task API that initiated the task. |
link | string | The URL of the task that initiated this task. |
selfLink | string | The URL to access this item directly. |
siloFilter | string | Restricts the restore to one silo. Input for full restore, output for partial restore. |
skippedItems | array | A list of configuration items that are in the snapshots but which were not created by the restore task, because the current module does not own these kinds. The list contains the actual state objects. |
link | string | URL of skipped item |
skipRestore | boolean | True means this is an evaluation of the differences without a restore. The task can optionally be resumed after inspection. |
skipVerifyConfig | boolean | If true, do not run verification after restore. |
snapshotReference | object | The snapshot from which objects are to be restored. |
link | string | URL of the snapshot |
snapshotWorkingConfig | boolean | Make a new snapshot of working-config before actual restore. |
specifiedObjectsOnly | boolean | In partial mode, do not follow reference chains. Use of this requires knowledge that the result will be useful. |
startDateTime | string | The time the task was started. |
status | string | Task status, updated during execution. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker |
type | string | Type of restore, “Full” or “Partial”. Read-only field. |
username | string | The user that initiated the task. |
userReference | object | The user that initiated the task. |
link | string | The URL of the user. |
verifyConfigReference | object | Reference to the verification result created by the verification task. |
link | string | URL of the verification result |
verifyConfigTaskReference | object | Reference to the verification task created by this restore task. |
link | string | URL of the verification task |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
GET /cm/<module>/tasks/restore-config/<id>¶
To check the status of a task you can send a GET request to the <module>/tasks/restore-config/<id> endpoint and specify the task’s id. In the following, <module> is a placeholder representing the module being deployed to. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe. 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 |
---|---|---|
clusterSyncTaskReferences | array | List of references to cluster-sync tasks created by this restore task. |
link | string | URL of the cluster-sync task |
configCopyTaskReference | object | Reference to the config-copy task created by this restore task. |
link | string | URL of the config-copy task task |
coordinationOpCount | number | Count of coordination operations sent by this restore task. |
coordinationTaskId | string | An existing coordination id that the restore task should use. |
createdSnapshotTaskReference | object | Reference to the snapshot task created by this restore task. |
link | string | URL of the snapshot task |
currentStep | string | Indicates what the task is currently doing. Possible values: “INIT”, “CHECK_FOR_RUNNING_TASKS”, “GET_SNAPSHOT”, “START_CHILD_TASK_EVAL”, “CHECK_CLUSTERS”, “VALIDATE_SILO”, “CREATE_DIFFERENCE”, “VERIFY_DIFFERENCE”, “WAIT_FOR_CHILD_TASK_EVAL”, “PENDING_CONFIRMATION”, “CREATE_SNAPSHOT”, “START_COORDINATION”, “START_CHILD_TASKS_COPY_CONFIG”, “COPY_CONFIG”, “SETUP_LSO”, “GET_CLUSTER_GROUPS”, “SYNC_CLUSTER_GROUPS”, “WAIT_FOR_START_CHILD_TASKS_COPY_CONFIG”, “PRE_COMMIT”, “COMMIT_COORDINATION”, “PENDING_VERIFY_CONFIG”, “START_CHILD_TASK_VERIFY_CONFIG”, “VERIFY_CONFIG”, “WAIT_FOR_CHILD_TASK_VERIFY_CONFIG” or “DONE”. |
description | string | Optional description for task |
deviceDetails | array | Tracks restore details, not necessarily device-related. Shared objects if deviceReference and deviceGroupReference are both null. |
currentSilo | string | The silo containing the device or device-group in the live system. |
deviceGroupReference | object | Device-group reference, for device-group-specific config items. |
link | string | The URL of device group |
deviceReference | object | Device reference, for device-specific config items. |
link | string | The URL of the device. |
hostname | number | Host name for device. |
notFound | boolean | Device or device-group does not exist; restore skipped. |
siloChanged | boolean | Device or device-group has been moved to a different silo since snapshot was taken. |
verificationCriticalErrorCount | number | Critical error count from verification task. |
verificationErrorCount | number | Non-critical error count from verification task. |
deviceGroupReference | object | Access only; device-group reference from the snapshot. |
link | string | URL of the device group |
differenceReference | object | Reference to the difference result created by the differencer task. |
link | string | URL of the difference result |
differenceTaskReference | object | Reference to the differencer task created by this restore task. |
link | string | URL of the device group |
endDateTime | string | The time the task ended. |
errorMessage | string | An error encountered while the task was running. There may be errors even when the task is not “FAILED”. |
id | string | The id for the item in the collection, used when accessing it directly. |
identityReferences | array | A list of user identities that initiated the task |
link | string | The URL of the identity. |
name | string | Name for the task |
noDifferenceFound | boolean | Copy of noDifferenceFound flag from the difference result (for client convenience). |
objectReferences | array | Indicates partial or selective restore. References to objects in the config to use as starting points for configuration enumeration. |
link | string | URL of the object |
ownerMachineId | string | In a high-availability environment, the machineId of the host running the task |
parentTaskReference | object | The task API that initiated the task. |
link | string | The URL of the task that initiated this task. |
selfLink | string | The URL to access this item directly. |
siloFilter | string | Restricts the restore to one silo. Input for full restore, output for partial restore. |
skippedItems | array | A list of configuration items that are in the snapshots but which were not created by the restore task, because the current module does not own these kinds. The list contains the actual state objects. |
link | string | URL of skipped item |
skipRestore | boolean | True means this is an evaluation of the differences without a restore. The task can optionally be resumed after inspection. |
skipVerifyConfig | boolean | If true, do not run verification after restore. |
snapshotReference | object | The snapshot from which objects are to be restored. |
link | string | URL of the snapshot |
snapshotWorkingConfig | boolean | Make a new snapshot of working-config before actual restore. |
specifiedObjectsOnly | boolean | In partial mode, do not follow reference chains. Use of this requires knowledge that the result will be useful. |
startDateTime | string | The time the task was started. |
status | string | Task status, updated during execution. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker |
type | string | Type of restore, “Full” or “Partial”. Read-only field. |
username | string | The user that initiated the task. |
userReference | object | The user that initiated the task. |
link | string | The URL of the user. |
verifyConfigReference | object | Reference to the verification result created by the verification task. |
link | string | URL of the verification result |
verifyConfigTaskReference | object | Reference to the verification task created by this restore task. |
link | string | URL of the verification task |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
PATCH mgmt/cm/<module>/tasks/restore-config/<id>¶
To cancel a running restore task, you can send a PATCH request to the <module>/tasks/restore-config 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 resume a restore task having a status of “FINISHED” and a currentStep of “PENDING_CONFIRMATION”, PATCH the status to “STARTED” and skipRestore to false.
Request Parameters¶
The request parameters in the PATCH request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
skipRestore | boolean | False | To restart a task that has been suspended for evaluation, change the skipRestore to false. |
status | string | True | To cancel a running task, send a PATCH request to change the value of status to “CANCEL_REQUESTED”. To restart a task that has been suspended for evaluation and restore change the status from “FINISHED” to “STARTED”. |
Response¶
HTTP/1.1 200 OK
The JSON in the response to a PATCH request can be the same as a GET to retrieve the task’s state.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
DELETE mgmt/cm/<module>/tasks/restore-config/<id>¶
To delete a task you can send a DELETE request to the <module>/tasks/restore-config 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 response to a DELETE request will be the same as a GET to retrieve the task’s state.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
Examples¶
POST to restore¶
The <module> is a placeholder representing the module being restored. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
POST https://<BIG-IQ>/mgmt/cm/<module>/tasks/restore-config
The following example creates a task to restore the working-config for module on BIG-IQ. The JSON in the body of the POST can be similar to the following.
{
"name": "restore-firewalls",
"description": "Undo mistakes from last week",
"snapshotReference": {
"link": "https://localhost/mgmt/cm/firewall/working-config/snapshots/e9287c1f-a217-4918-974a-31aeff6fe33d"
},
"siloFilter": "bad-devices",
"objectReferences": [{
"link": "https://localhost/mgmt/cm/adc-core/working-config/ltm/virtual/28b8de45-766e-3aea-a4eb-3f115d014f27"
}],
"specifiedObjectsOnly": false,
"snapshotWorkingConfig": false,
"skipRestore": true,
"skipVerifyConfig": true,
"coordinationTaskId": null
}
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": "restore-firewalls",
"description": "Undo mistakes from last week",
"snapshotReference": {
"link": "https://localhost/mgmt/cm/firewall/working-config/snapshots/e9287c1f-a217-4918-974a-31aeff6fe33d"
},
"siloFilter": "bad-devices",
"objectReferences": [{
"link": "https://localhost/mgmt/cm/adc-core/working-config/ltm/virtual/28b8de45-766e-3aea-a4eb-3f115d014f27"
}],
"specifiedObjectsOnly": false,
"snapshotWorkingConfig": false,
"skipRestore": true,
"skipVerifyConfig": true,
"coordinationTaskId": null,
"currentStep": "INIT",
"coordinationOpCount": 42,
"skippedItems": [{}],
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/default-access-group"
},
"differenceTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/difference-config/15cb9909-f530-401b-b1c4-e2640cee28cd"
},
"differenceReference": {
"link": "https://localhost/mgmt/cm/firewall/reports/config-differences/d81a5f96-33f1-431c-8d30-9e697cdbe6bf"
},
"noDifferenceFound": false,
"createdSnapshotTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/snapshot-config/b286caa5-7a9f-4e62-b671-1c002d11cb80"
},
"configCopyTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/working-config-copy/9022bfbb-5e8f-4c68-9aa7-7cdee6d2ebe2"
},
"clusterSyncTaskReferences": [{
"link": "https://localhost/mgmt/cm/firewall/tasks/cluster-sync/c23355c3-90bf-4727-ac6c-7aed51d4fe37"
}],
"verifyConfigTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/verify-config/5952c913-89b1-4bb6-9e08-fcdd84749ded"
},
"verifyConfigReference": {
"link": "https://localhost/mgmt/cm/firewall/reports/config-verifications/e818d4fb-7f77-4ed6-a8db-a3df0babfd76"
},
"deviceDetails": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-firewall-allFirewallDevices/devices/eb0a70b9-ebb8-4cec-a04b-7196bfcbbc7d"
},
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-dns-billerica"
},
"notFound": false,
"siloChanged": false,
"currentSilo": "bad-devices",
"verificationErrorCount": 1,
"verificationCriticalErrorCount": 0,
"hostname": "theusz-hamtaahk.billerica.org"
}],
"type": "Full",
"generation": 7,
"lastUpdateMicros": 1566226520520009,
"kind": "cm:<module>:tasks:restore-config:restoreworkingconfigtaskitemstate",
"selfLink": "https://localhost/mgmt/cm/<module>/tasks/restore-config/85f738ed-5419-4fee-8f26-a60fbf4a06bf",
"id": "85f738ed-5419-4fee-8f26-a60fbf4a06bf",
"status": "STARTED",
"startDateTime": "2019-08-19T12:13:18.540-0400",
"errorMessage": "Restore task can not run while deploy task is running",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "4418595c-c687-45ed-ad47-371e94ee332c",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/restore-config/28cfc00c-573b-4f20-881c-278ab8278914"
}
}
GET to check the updated 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”. The <module> is a placeholder representing the module being deployed to. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
GET https://<BIG-IQ>/mgmt/cm/<module>/tasks/restore-config/<id>
Response¶
The JSON in the response to the GET when the task is done can look similar to the following.
{
"name": "restore-firewalls",
"description": "Undo mistakes from last week",
"snapshotReference": {
"link": "https://localhost/mgmt/cm/firewall/working-config/snapshots/e9287c1f-a217-4918-974a-31aeff6fe33d"
},
"siloFilter": "bad-devices",
"objectReferences": [{
"link": "https://localhost/mgmt/cm/adc-core/working-config/ltm/virtual/28b8de45-766e-3aea-a4eb-3f115d014f27"
}],
"specifiedObjectsOnly": false,
"snapshotWorkingConfig": false,
"skipRestore": true,
"skipVerifyConfig": true,
"coordinationTaskId": null,
"currentStep": "INIT",
"coordinationOpCount": 42,
"skippedItems": [{}],
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/default-access-group"
},
"differenceTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/difference-config/15cb9909-f530-401b-b1c4-e2640cee28cd"
},
"differenceReference": {
"link": "https://localhost/mgmt/cm/firewall/reports/config-differences/d81a5f96-33f1-431c-8d30-9e697cdbe6bf"
},
"noDifferenceFound": false,
"createdSnapshotTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/snapshot-config/b286caa5-7a9f-4e62-b671-1c002d11cb80"
},
"configCopyTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/working-config-copy/9022bfbb-5e8f-4c68-9aa7-7cdee6d2ebe2"
},
"clusterSyncTaskReferences": [{
"link": "https://localhost/mgmt/cm/firewall/tasks/cluster-sync/c23355c3-90bf-4727-ac6c-7aed51d4fe37"
}],
"verifyConfigTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/verify-config/5952c913-89b1-4bb6-9e08-fcdd84749ded"
},
"verifyConfigReference": {
"link": "https://localhost/mgmt/cm/firewall/reports/config-verifications/e818d4fb-7f77-4ed6-a8db-a3df0babfd76"
},
"deviceDetails": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-firewall-allFirewallDevices/devices/eb0a70b9-ebb8-4cec-a04b-7196bfcbbc7d"
},
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-dns-billerica"
},
"notFound": false,
"siloChanged": false,
"currentSilo": "bad-devices",
"verificationErrorCount": 1,
"verificationCriticalErrorCount": 0,
"hostname": "theusz-hamtaahk.billerica.org"
}],
"type": "Full",
"generation": 7,
"lastUpdateMicros": 1566226520520009,
"kind": "cm:<module>:tasks:restore-config:restoreworkingconfigtaskitemstate",
"selfLink": "https://localhost/mgmt/cm/<module>/tasks/restore-config/85f738ed-5419-4fee-8f26-a60fbf4a06bf",
"id": "85f738ed-5419-4fee-8f26-a60fbf4a06bf",
"status": "STARTED",
"startDateTime": "2019-08-19T12:13:18.540-0400",
"errorMessage": "Restore task can not run while deploy task is running",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "4418595c-c687-45ed-ad47-371e94ee332c",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/restore-config/28cfc00c-573b-4f20-881c-278ab8278914"
}
}
PATCH to cancel a running task¶
You can send a PATCH request to cancel a running task specified by the task’s id. The <module> is a placeholder representing the module being deployed to. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
PATCH https://<BIG-IQ>/mgmt/cm/<module>/tasks/restore-config/<id>
In the body of the PATCH request specify the value of status as “CANCEL_REQUESTED”.
{
"status": "CANCEL_REQUESTED"
}
Response¶
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 and restore¶
You can send a PATCH request to restart a task that has been evaluated without restoring. Specify the task to restart by the task’s id. The <module> is a placeholder representing the module being deployed to. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
PATCH https://<BIG-IQ>/mgmt/cm/<module>/tasks/restore-config/<id>
In the body of the PATCH request specify the value of status as “STARTED” and the value of “skipDistribution” to false.
{
"skipRestore": false,
"status": "STARTED"
}
Response¶
Send repeated GET requests to poll the task until the value of status updates to “FINISHED” or “FAILED”.
PATCH to modify a task¶
You can send a PATCH request to modify a task. Specify the task to restart by the task’s id. The <module> is a placeholder representing the module being deployed to. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
PATCH https://<BIG-IQ>/mgmt/cm/<module>/tasks/restore-config/<id>
In the body of the PATCH request specify the new values of the changed parameters.
{
"name": "restore-firewalls",
"description": "Undo mistakes from last week",
"snapshotReference": {
"link": "https://localhost/mgmt/cm/firewall/working-config/snapshots/e9287c1f-a217-4918-974a-31aeff6fe33d"
},
"siloFilter": "bad-devices",
"objectReferences": [{
"link": "https://localhost/mgmt/cm/adc-core/working-config/ltm/virtual/28b8de45-766e-3aea-a4eb-3f115d014f27"
}],
"specifiedObjectsOnly": false,
"snapshotWorkingConfig": false,
"skipRestore": true,
"skipVerifyConfig": true,
"coordinationTaskId": null
}
Response¶
The JSON in the body of the response to the PATCH can be similar to the following.
{
"name": "restore-firewalls",
"description": "Undo mistakes from last week",
"snapshotReference": {
"link": "https://localhost/mgmt/cm/firewall/working-config/snapshots/e9287c1f-a217-4918-974a-31aeff6fe33d"
},
"siloFilter": "bad-devices",
"objectReferences": [{
"link": "https://localhost/mgmt/cm/adc-core/working-config/ltm/virtual/28b8de45-766e-3aea-a4eb-3f115d014f27"
}],
"specifiedObjectsOnly": false,
"snapshotWorkingConfig": false,
"skipRestore": true,
"skipVerifyConfig": true,
"coordinationTaskId": null,
"currentStep": "INIT",
"coordinationOpCount": 42,
"skippedItems": [{}],
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/default-access-group"
},
"differenceTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/difference-config/15cb9909-f530-401b-b1c4-e2640cee28cd"
},
"differenceReference": {
"link": "https://localhost/mgmt/cm/firewall/reports/config-differences/d81a5f96-33f1-431c-8d30-9e697cdbe6bf"
},
"noDifferenceFound": false,
"createdSnapshotTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/snapshot-config/b286caa5-7a9f-4e62-b671-1c002d11cb80"
},
"configCopyTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/working-config-copy/9022bfbb-5e8f-4c68-9aa7-7cdee6d2ebe2"
},
"clusterSyncTaskReferences": [{
"link": "https://localhost/mgmt/cm/firewall/tasks/cluster-sync/c23355c3-90bf-4727-ac6c-7aed51d4fe37"
}],
"verifyConfigTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/verify-config/5952c913-89b1-4bb6-9e08-fcdd84749ded"
},
"verifyConfigReference": {
"link": "https://localhost/mgmt/cm/firewall/reports/config-verifications/e818d4fb-7f77-4ed6-a8db-a3df0babfd76"
},
"deviceDetails": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-firewall-allFirewallDevices/devices/eb0a70b9-ebb8-4cec-a04b-7196bfcbbc7d"
},
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-dns-billerica"
},
"notFound": false,
"siloChanged": false,
"currentSilo": "bad-devices",
"verificationErrorCount": 1,
"verificationCriticalErrorCount": 0,
"hostname": "theusz-hamtaahk.billerica.org"
}],
"type": "Full",
"generation": 7,
"lastUpdateMicros": 1566226520520009,
"kind": "cm:<module>:tasks:restore-config:restoreworkingconfigtaskitemstate",
"selfLink": "https://localhost/mgmt/cm/<module>/tasks/restore-config/85f738ed-5419-4fee-8f26-a60fbf4a06bf",
"id": "85f738ed-5419-4fee-8f26-a60fbf4a06bf",
"status": "STARTED",
"startDateTime": "2019-08-19T12:13:18.540-0400",
"errorMessage": "Restore task can not run while deploy task is running",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "4418595c-c687-45ed-ad47-371e94ee332c",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/restore-config/28cfc00c-573b-4f20-881c-278ab8278914"
}
}
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. The <module> is a placeholder representing the module being deployed to. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
DELETE https://<BIG-IQ>/mgmt/cm/<module>/tasks/restore-config/<id>
Response¶
The JSON in the response from a DELETE request is similar to the response from a GET request.