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.

Previous Next