Configuration Snapshot¶
Overview¶
Use the Configuration Snapshot API to create a task to make a snapshot of a specific module object in the BIG-IQ’s working-config. A snapshot can record the state of the working-config objects for a specified module even when those objects are subsequently modified or deleted. Separate tasks are required to record the configurations of different modules (i.e. access, adc-core, asm, dns, firewall, security-shared or websafe.) Use the Configuration Restore API to restore the working-config on the BIG-IQ to a previous snapshot. 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.
REST Endpoint: mgmt/cm/<module>/tasks/snapshot-config¶
Requests¶
To start the snapshot task, send a POST request to the <module>/tasks/snapshot-config endpoint. The placeholder text <module> represents the module being snapshot. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
POST mgmt/cm/<module>/tasks/snapshot-config¶
Request Parameters¶
The JSON in the body of the POST request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
name | string | True | Name for the task |
description | string | False | Optional description for task |
deviceGroupReference | object | False | For use with access module only. Has no effect on snapshot creation but allows a device-group name to be recorded as a snapshot. |
link | string | False | URL of the device-group |
Query Parameters¶
None
Response¶
The JSON in the body of the response to the POST request represents the initial state of the snapshot 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 |
---|---|---|
currentStep | number | Internal processing step updated during execution to show progress. Possible values: “INIT”, “PRE_PROCESS”, “CREATE_GLOBAL_SNAPSHOT”, “START_CHILD_SNAPSHOT_TASKS”, “WAIT_FOR_CHILD_SNAPSHOT_TASKS”, “COMPLETE_SNAPSHOT” or “DONE”. |
description | string | Optional description for task |
deviceGroupReference | object | For use with access module only. Has no effect on snapshot creation but allows a device-group name to be recorded as a snapshot. |
link | string | URL of device-group |
endDateTime | string | Time the task stopped |
era | number | The era assigned to the snapshot. |
errorMessage | string | An error encountered while the task was running. There can be errors even if status is not “FAILED”. |
globalSnapshotReference | object | Reference to the storage view of the snapshot (not accessible to external client). |
link | string | URL of the global snapshot |
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. |
isOwnerOnly | boolean | True if snapshot taken in HA situation. Restricts subsequent use of snapshot. |
modules | string | Modules included in the global snapshot. For this module snapshot task, the list will contain only a single module. |
name | string | 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 | The URL of the task that initiated this task. |
selfLink | string | The URL to access this item directly. |
snapshotReference | object | Reference to the snapshot that was created. |
link | string | URL of the snapshot |
startDateTime | string | The time the task was started. |
status | string | Current 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 |
username | string | The user that initiated the task. |
userReference | object | The user that initiated the task. |
link | string | URL of the user. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
GET /cm/<module>/tasks/snapshot-config/<id>¶
To check the status of a task you can send a GET request to the <module>/tasks/snapshot-config/<id> endpoint and specify the task’s id. In the following, <module> is a placeholder representing the module being deployed. 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 |
---|---|---|
currentStep | number | Internal processing step, updated during execution to show progress. Possible values: “INIT”, “PRE_PROCESS”, “CREATE_GLOBAL_SNAPSHOT”, “START_CHILD_SNAPSHOT_TASKS”, “WAIT_FOR_CHILD_SNAPSHOT_TASKS”, “COMPLETE_SNAPSHOT” or “DONE”. |
description | string | Optional description for task |
deviceGroupReference | object | Access module only. Has no effect on snapshot creation but allows a device-group name to be stored in the snapshot |
link | string | URL of the device group |
endDateTime | string | The time the task stopped running. |
era | number | The era assigned to the snapshot. |
errorMessage | string | An error encountered while the task was running. There may be errors even when the task is not FAILED. |
globalSnapshotReference | object | Reference to the storage view of the snapshot (not accessible to external client). |
link | string | URL of the global snapshot |
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. |
isOwnerOnly | boolean | True if snapshot taken in HA situation. Restricts subsequent use of snapshot. |
modules | string | Modules included in the global snapshot. For this module snapshot task, the list will contain only a single module. |
name | string | 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 | The URL of the task that initiated this task. |
selfLink | string | The URL to access this item directly. |
snapshotReference | object | Reference to the snapshot that was created. |
link | string | URL of the snapshot |
startDateTime | string | The time the task was started. |
status | string | Current 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 |
username | string | The user that initiated the task. |
userReference | object | The user that initiated the task. |
link | string | URL of the user. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
<module>_Common_Viewer | Yes |
<module>_Deploy | Yes |
<module>_Manager | Yes |
PATCH mgmt/cm/<module>/tasks/snapshot-config/<id>¶
To modify a snapshot task, you can send a PATCH request to the <module>/tasks/snapshot-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.
Request Parameters¶
The request parameters in the PATCH request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
name | string | True | Name for the task |
description | string | False | Optional description for task |
deviceGroupReference | object | False | Access module only. Has no effect on snapshot creation but allows a device-group name to be stored in the snapshot |
link | string | False | URL of the device group |
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/snapshot-config/<id>¶
To delete a task you can send a DELETE request to the <module>/tasks/snapshot-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. Snapshot tasks and the associated snapshots must be explicitly deleted by clients, since they represent valuable data. Deleting the snapshot task automatically deletes the snapshot as well; and deleting the snapshot allows underlying object generations to be discarded if there are no further references to them.
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 snapshot¶
The <module> is a placeholder representing the module having a snapshot. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
POST https://<BIG-IQ>/mgmt//cm/<module>/tasks/snapshot-config
The following example creates a task to snapshot the configuration for module on the specified BIG-IP. The JSON in the body of the POST can be similar to the following.
{
"name": "sample-name",
"description": "sample-description",
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/default-access-group"
}
}
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": "sample-name",
"description": "sample-description",
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/default-access-group"
},
"snapshotReference": {
"link": "https://localhost/mgmt/cm/<module>/working-config/snapshots/787e4aa4-023e-479f-bb44-8dbcc1a1b06f"
},
"globalSnapshotReference": {
"link": "https://localhost/mgmt/shared/storage/snapshots/5850e120-4e66-4859-b664-50efd48ea846"
},
"era": 27,
"isOwnerOnly": true,
"modules": [
"firewall"
],
"currentStep": "INIT",
"generation": 42,
"lastUpdateMicros": 1565807553877017,
"kind": "cm:<module>:tasks:snapshot-config:snapshottaskstate",
"selfLink": "https://localhost/mgmt/cm/<module>/tasks/snapshot-config/9830787d-1a00-41d5-b5ab-5abfe0f9c77d",
"id": "9830787d-1a00-41d5-b5ab-5abfe0f9c77d",
"status": "STARTED",
"startDateTime": "2019-08-14T14:43:56.439-0400",
"errorMessage": "Failed to start child snapshot task",
"userReference": {
"link": "admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "d26f3d5f-5190-4ad0-8697-a15b1588653f",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/deploy-configuration/13dee3af-a692-42a1-8801-2a2c34113a1d"
}
}
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. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
GET https://<BIG-IQ>/mgmt/cm/global/tasks/snapshot-config/<id>
Response¶
The JSON in the response to the GET when the task is done can look similar to the following.
{
"name": "sample-name",
"description": "sample-description",
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/default-access-group"
},
"snapshotReference": {
"link": "https://localhost/mgmt/cm/<module>/working-config/snapshots/787e4aa4-023e-479f-bb44-8dbcc1a1b06f"
},
"globalSnapshotReference": {
"link": "https://localhost/mgmt/shared/storage/snapshots/5850e120-4e66-4859-b664-50efd48ea846"
},
"era": 27,
"isOwnerOnly": true,
"modules": [
"firewall"
],
"currentStep": "INIT",
"generation": 42,
"lastUpdateMicros": 1565807553877017,
"kind": "cm:<module>:tasks:snapshot-config:snapshottaskstate",
"selfLink": "https://localhost/mgmt/cm/<module>/tasks/snapshot-config/9830787d-1a00-41d5-b5ab-5abfe0f9c77d",
"id": "9830787d-1a00-41d5-b5ab-5abfe0f9c77d",
"status": "STARTED",
"startDateTime": "2019-08-14T14:43:56.439-0400",
"errorMessage": "Failed to start child snapshot task",
"userReference": {
"link": "admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "d26f3d5f-5190-4ad0-8697-a15b1588653f",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/deploy-configuration/13dee3af-a692-42a1-8801-2a2c34113a1d"
}
}
PATCH to cancel a running task¶
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. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
PATCH https://<BIG-IQ>/mgmt/cm/<module>/tasks/snapshot-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 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. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
PATCH https://<BIG-IQ>/mgmt/cm/<module>/tasks/snapshot-config/<id>
In the body of the PATCH request specify the new values of the changed parameters.
{
"name": "sample-name",
"description": "sample-description",
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/default-access-group"
}
}
Response¶
The JSON in the body of the response to the PATCH can be similar to the following.
{
"name": "sample-name",
"description": "sample-description",
"deviceGroupReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/default-access-group"
},
"snapshotReference": {
"link": "https://localhost/mgmt/cm/<module>/working-config/snapshots/787e4aa4-023e-479f-bb44-8dbcc1a1b06f"
},
"globalSnapshotReference": {
"link": "https://localhost/mgmt/shared/storage/snapshots/5850e120-4e66-4859-b664-50efd48ea846"
},
"era": 27,
"isOwnerOnly": true,
"modules": [
"firewall"
],
"currentStep": "INIT",
"generation": 42,
"lastUpdateMicros": 1565807553877017,
"kind": "cm:<module>:tasks:snapshot-config:snapshottaskstate",
"selfLink": "https://localhost/mgmt/cm/<module>/tasks/snapshot-config/9830787d-1a00-41d5-b5ab-5abfe0f9c77d",
"id": "9830787d-1a00-41d5-b5ab-5abfe0f9c77d",
"status": "STARTED",
"startDateTime": "2019-08-14T14:43:56.439-0400",
"errorMessage": "Failed to start child snapshot task",
"userReference": {
"link": "admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "d26f3d5f-5190-4ad0-8697-a15b1588653f",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/firewall/tasks/deploy-configuration/13dee3af-a692-42a1-8801-2a2c34113a1d"
}
}
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 task¶
The following example deletes the task identified by id. The <module> is a placeholder representing the module being deployed. The possible values of <module> are access, adc-core, asm, dns, firewall, security-shared or websafe.
DELETE https://<BIG-IQ>/mgmt/cm/<module>/tasks/deploy-configuration/<id>
Response¶
The JSON in the response from a DELETE request is similar to the response from a GET request.