Snapshots
Snapshots are simply copies of your virtual server, similar to Templates, as they retain all the data of your machine but have the following differences:
- It is possible to restore a server's state from a Snapshot
- A Snapshot cannot be used to create a new machine
- A Snapshot can be converted into a Template but not vice versa
Protected Snapshots
Snapshots are divided into protected and unprotected Snapshots with the following characteristics:
| # | Protected | Unprotected |
|---|---|---|
| Creation | Protected Snapshots are created manually | Unprotected Snapshots are created by periodic processes |
| Maximum Retention | Protected Snapshots are not subject to maximum retention | Unprotected Snapshots can be deleted based on the maximum retention |
| Maximum Quantity | The maximum number of protected Snapshots is 12 | The maximum number of unprotected Snapshots depends on the maximum retention |
| Conversion | Protected Snapshots cannot be converted to unprotected ones | Unprotected Snapshots can be converted to protected ones |
Managing Snapshots
Our services provide several HTTP calls to manage Snapshots. Below are the most common operations:
Create a Snapshot
The following request is available to create a snapshot:
HTTP Request
POST /ecs/v2/servers/{servername}/snapshots
{
"description": "my-first-snapshot",
"notes": "my-first-snapshot"
}
HTTP Response
{
"status": "ok",
"snapshot": {
"id": 104,
"name": "ec200409-SNP-1",
"user": "admin",
"snapshot_parent": null,
"snapshot_parent_name": null,
"is_last_restored": false,
"protected": true,
"restoring": false,
"source_server": "ec200409",
"status": "CG",
"status_label": "Creating",
"uid": "eb7e9539-3f77-4ebc-811d-58237521a8cc",
"description": "my-first-snapshot",
"notes": "my-first-snapshot",
"active_flag": false,
"size_on_disk": null,
"created_at": "2025-02-07T12:50:02.840Z",
"updated_at": "2025-02-07T12:50:02.840Z",
"deleted_at": null,
"api_version_value": 5,
"api_version": "v5"
},
"action": {
"id": 2115,
"status": "in-progress",
"user": "admin",
"created_at": "2025-02-07T12:50:02.846870+00:00",
"started_at": "2025-02-07T12:50:02.846406+00:00",
"completed_at": null,
"resource": "104",
"resource_type": "SNP",
"type": "create_snapshot",
"progress": 0
}
}
| Status Code | Message | Explanation |
|---|---|---|
| 400 | server in current status can't generate snapshot | The server is not yet ready to generate Snapshots |
| 400 | can't create a snapshot if there is snapshot pending for selected server | To create a new Snapshot, there must be no pending Snapshots |
| 400 | can't create a snapshot if there is more than 12 protected snapshot for selected server | It is not possible to create more than 12 protected Snapshots |
Viewing All Snapshots
The following call is available to view all Snapshots:
HTTP Request:
GET /ecs/v2/servers/{servername}/snapshots
HTTP Response
{
"status": "ok",
"snapshots": [
{
"id": 104,
"name": "ec200409-SNP-1",
"user": "admin",
"snapshot_parent": null,
"snapshot_parent_name": null,
"is_last_restored": true,
"protected": true,
"restoring": false,
"source_server": "ec200409",
"status": "CD",
"status_label": "Created",
"uid": "eb7e9539-3f77-4ebc-811d-58237521a8cc",
"description": "my-first-snapshot",
"notes": "my-first-snapshot",
"active_flag": true,
"size_on_disk": 3804560,
"created_at": "2025-02-07T12:50:02.840Z",
"updated_at": "2025-02-07T12:52:03.301Z",
"deleted_at": null,
"api_version_value": 5,
"api_version": "v5"
}
]
}
Retrieving a Specific Snapshot
The following call is available to retrieve a specific Snapshot:
HTTP Request
GET /ecs/v2/servers/{servername}/snapshots/{snapshot_id}
HTTP Response
{
"status": "ok",
"snapshot": {
"id": 104,
"name": "ec200409-SNP-1",
"user": "admin",
"snapshot_parent": null,
"snapshot_parent_name": null,
"is_last_restored": true,
"protected": true,
"restoring": false,
"source_server": "ec200409",
"status": "CD",
"status_label": "Created",
"uid": "eb7e9539-3f77-4ebc-811d-58237521a8cc",
"description": "my-first-snapshot",
"notes": "my-first-snapshot",
"active_flag": true,
"size_on_disk": 3804560,
"created_at": "2025-02-07T12:50:02.840Z",
"updated_at": "2025-02-07T12:52:03.301Z",
"deleted_at": null,
"api_version_value": 5,
"api_version": "v5"
}
}
Modifying a Snapshot
Of course, it is also possible to modify some information of a Snapshot:
HTTP Request
PATCH /ecs/v2/servers/{servername}/snapshots/{snapshot_id}
{
"description": "new-snap-description", //update snapshot description
"notes": "new-snap-notes", //update snapshot notes
"protected": true //protect a server
}
HTTP Response
{
"status": "ok",
"snapshot": {
"id": 104,
"name": "ec200409-SNP-1",
"user": "admin",
"snapshot_parent": null,
"snapshot_parent_name": null,
"is_last_restored": true,
"protected": true,
"restoring": false,
"source_server": "ec200409",
"status": "CD",
"status_label": "Created",
"uid": "eb7e9539-3f77-4ebc-811d-58237521a8cc",
"description": "new-snap-description",
"notes": "new-snap-description",
"active_flag": true,
"size_on_disk": 3804560,
"created_at": "2025-02-07T12:50:02.840Z",
"updated_at": "2025-02-07T13:11:20.196Z",
"deleted_at": null,
"api_version_value": 5,
"api_version": "v5"
}
}
| Status Code | Message | Explanation |
|---|---|---|
| 400 | can't convert a protected snapshot to not protected | It is not possible to convert a protected Snapshot to unprotected |
| 400 | can't have more then 12 protected snapshot | It is not possible to have more than 12 protected Snapshots |
Deleting a Snapshot
Finally, if no longer needed, it is possible to destroy a Snapshot:
HTTP Request
DELETE /ecs/v2/servers/ec200409/snapshots/104
HTTP Response
{
"status": "ok",
"snapshot": {
"id": 104,
"name": "ec200409-SNP-1",
"user": "admin",
"snapshot_parent": null,
"snapshot_parent_name": null,
"is_last_restored": true,
"protected": true,
"restoring": false,
"source_server": "ec200409",
"status": "DE",
"status_label": "Deleting",
"uid": "eb7e9539-3f77-4ebc-811d-58237521a8cc",
"description": "new-snap-description",
"notes": "new-snap-description",
"active_flag": false,
"size_on_disk": 3804560,
"created_at": "2025-02-07T12:50:02.840Z",
"updated_at": "2025-02-07T13:12:44.450Z",
"deleted_at": "2025-02-07T13:12:44.447Z",
"api_version_value": 5,
"api_version": "v5"
},
"action": {
"id": 2116,
"status": "in-progress",
"user": "admin",
"created_at": "2025-02-07T13:12:44.442950+00:00",
"started_at": "2025-02-07T13:12:44.440924+00:00",
"completed_at": null,
"resource": "104",
"resource_type": "SNP",
"type": "delete_snapshot",
"progress": 0
}
}
Periodic Snapshots
It is also possible to use snapshots in a scheduled manner to allow weekly protection of the Server.
To do this, it is necessary to configure a Cron on the relevant Server.
Currently, the available configuration is exclusively on a weekly basis with the following parameters:
| Day of the Week (day_of_week) | Maximum Retention (max_retention) |
|---|---|
| 0 (Sunday) | 2 |
| 1 (Monday) | 4 |
| 2 (Tuesday) | |
| 3 (Wednesday) | |
| 4 (Thursday) | |
| 5 (Friday) | |
| 6 (Saturday) |
Info
Maximum retention indicates the maximum number of unprotected snapshots allowed. If creating a new Snapshot exceeds this number, the oldest unprotected Snapshot will be deleted in advance.
Configuring a Periodic Snapshot
The following request is available to configure a periodic Snapshot:
HTTP Request
POST /ecs/v2/servers/{servername}/crons
{
"type": "snapshot_schedule",
"config": {
"typology": "weekly",
"max_retention": 2,
"day_of_week": 0
}
}
HTTP Response
{
"status": "ok",
"cron": {
"name": "snapshot_schedule_ec200409",
"schedule": "0 0 * * 0 (m/h/dM/MY/d) UTC",
"enabled": true,
"last_run_at": null,
"infos": {
"max_retention": 2,
"day_of_week": 0
},
"last_run_status": null
}
}
Warning
The schedule attribute can be rescheduled over time within a time range between 00:00 and 06:00 UTC.
Viewing the Active Configuration
The following request can be used to view the currently active configuration:
HTTP Request
GET /ecs/v2/servers/{servername}/crons/snapshot_schedule_{servername}
HTTP Response
{
"status": "ok",
"cron": {
"name": "snapshot_schedule_ec200409",
"schedule": "0 0 * * 0 (m/h/dM/MY/d) UTC",
"enabled": true,
"last_run_at": null,
"infos": {
"max_retention": 2,
"day_of_week": 0
},
"last_run_status": null
}
}
Modifying the Active Configuration
The active configuration can also be modified without requiring a new creation request:
HTTP Request
PATCH /ecs/v2/servers/{servername}/crons/snapshot_schedule_{servername}
{
"enabled": true,
"max_retention": 2,
"day_of_week": 6
}
HTTP Response
{
"status": "ok",
"cron": {
"name": "snapshot_schedule_ec200409",
"schedule": "0 0 * * 0 (m/h/dM/MY/d) UTC",
"enabled": true,
"last_run_at": null,
"infos": {
"max_retention": 2,
"day_of_week": 0
},
"last_run_status": null
}
}
Deleting the Configuration
To delete the configuration and disable periodic Snapshots, the following request can be executed:
HTTP Request
DELETE /ecs/v2/servers/{servername}/crons/snapshot_schedule_{servername}
HTTP Response
{
"status": "ok",
"cron": {
"name": "snapshot_schedule_ec200409",
"schedule": "0 0 * * 0 (m/h/dM/MY/d) UTC",
"enabled": true,
"last_run_at": null,
"infos": {
"max_retention": 2,
"day_of_week": 0
},
"last_run_status": null
}
}