Snapshots
Snapshots are read-only point-in-time images of volumes. They are created once
and cannot be changed. They can be attached to hosts as read-only block devices
under /dev/storpool
.
Volumes and snapshots share the same name-space, thus their names are unique within a StorPool cluster. Volumes can be based on snapshots. Such volumes contain only the changes since the snapshot was taken. After a volume is created from a snapshot, writes will be recorded within the volume. Reads from volume may be served by volume or by its parent snapshot depending on whether volume contains changed data for the read request or not.
For an overview of how snapshots work, see Volumes and snapshots.
Command parameters
You can perform snapshot operations on the command line using the
storpool snapshot
command.
Common parameters
When there is no snapshot name specified to the storpool snapshot
command
you can use the following parameters:
list
Get a list of snapshots; for details, see Listing snapshots.
remote
In multi-site or multi-cluster scenarios a snapshot could be exported and become visible to other configured clusters; for details, see Remote snapshots.
space
Get the space that will be freed if a snapshot is deleted; see Deleting snapshots.
Snapshot-specific parameters
When there is snapshot name specified to the storpool snapshot
command
you can use the following parameters:
bind
Bind a snapshot to its child volumes; for details, see Deleting snapshots.
bw
Set maximum bandwidth limit (in MB/s).
delete
Delete a snapshot; for details, see Deleting snapshots.
delete
Set a snapshot for deferred deletion; for details, see Deleting snapshots.
export
Export a snapshot to a remote location; for details, see Remote snapshots.
list
List the target disk sets and objects of a snapshot; for details, see Listing snapshots.
info
Get detailed information about the disks used for a snapshot and the number of objects on each of them; for details, see Listing snapshots.
iops
Set the maximum IOPS limit for this snapshot (in IOPS).
limitType
Specify whether
iops
andbw
limits ought to be for the total size of the block device, or per each GiB (one of “total” or “perGiB”).Note
The bandwidth and IOPS limits are concerning only the particular snapshot if it is attached and does not limit any child volumes using this snapshot as parent.
moveToRemote
Move a snapshot to a different cluster; for details, see Moving snapshots.
placeAll
Name of the “All” placement group (see Placement groups). Default value: default.
placeTail
Name of the “Tail” placement group. Default value: same as the value of
placeAll
.placeHead
Name of the “Head” placement group. Default value: same as the value of
placeAll
.rebase
Rebase a snapshot to another parent; for details, see Promoting snapshots.
rename
Rename a snapshot; for details, see Renaming snapshots.
reuseServer
Place multiple copies on the same server.
tag
Set a tag in the form
key=value
. Here is an example:# storpool snapshot testsnapplustags tag key=value
template
Use template with preconfigured placement, replication, and/or limits (check Templates for details). Here is an example:
# storpool snapshot testsnap template all-ssd
unbind
Unbind a snapshot from volumes; for details, see Deleting snapshots.
unexport
Unexport a local snapshot; for details, see Remote snapshots.
Creating snapshots
To create an unnamed (known also as anonymous) snapshot of a volume:
# storpool volume testvolume snapshot
OK
This will create a snapshot named testvolume@<ID>
, where ID
is an unique
serial number. Note that any tags on the volume will not be propagated to the
snapshot; to set tags on the snapshot at creation time:
# storpool volume testvolume tag key=value snapshot
To create a named snapshot of a volume:
# storpool volume testvolume snapshot testsnap
OK
To directly set tags:
# storpool volume testvolume snapshot testsnapplustags tag key=value
To create a bound snapshot on a volume:
# storpool volume testvolume bound snapshot
OK
This snapshot will be automatically deleted when the last child volume created from it is deleted. Useful for non-persistent images.
Listing snapshots
To list the snapshots:
# storpool snapshot list
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| snapshot | size | rdnd. | placeHead | placeAll | placeTail | created on | volume | iops | bw | parent | template | flags | targetDeleteDate | tags |
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| testsnap | 100 GiB | 3 | hdd | hdd | ssd | 2019-08-30 04:11:23 | testvolume | - | - | testvolume@1430 | hybrid-r3 | | - | key=value |
| testvolume@1430 | 100 GiB | 3 | hdd | hdd | ssd | 2019-08-30 03:56:58 | testvolume | - | - | | hybrid-r3 | A | - | |
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Flags:
A - anonymous snapshot with auto-generated name
B - bound snapshot
D - snapshot currently in the process of deletion
T - transient snapshot (created during volume cloning)
R - allow placing two disks within a replication chain onto the same server
P - snapshot delete blocked due to multiple children
To list the snapshots only for a particular volume:
# storpool volume testvolume list snapshots
[snip]
To list the target disk sets and objects of a snapshot:
# storpool snapshot testsnap list
[snip]
The output is similar as with storpool volume <volumename> list
; for
details, see Listing disk sets and objects.
To get detailed info about the disks used for this snapshot and the number of objects on each of them:
# storpool snapshot testsnap info
[snip]
The output is similar to the storpool volume <volumename> info
.
Volume operations
To create a volume based on an existing snapshot (cloning):
# storpool volume testvolume parent centos73-base-snap
OK
To revert a volume to an existing snapshot:
# storpool volume testvolume revertToSnapshot centos73-working
OK
This is also possible through the use of templates with a parent snapshot (see Templates):
# storpool volume spd template centos73-base
OK
Create a volume based on another existing volume (cloning):
# storpool volume testvolume1 baseOn testvolume
OK
Note
This operation will first create an anonymous bound snapshot on
testvolume
and will then create testvolume1
with the bound
snapshot as parent. The snapshot will exist until both volumes are
deleted and will be automatically deleted afterwards.
Deleting snapshots
To delete a snapshot:
# storpool snapshot spdb_snap1 delete spdb_snap1
OK
Note
To avoid accidents, the name of the snapshot must be entered twice.
Sometimes the system would not delete the snapshot immediately; during this
period of time, it would be visible with *
in the output of storpool
volume status
or storpool snapshot list
.
To set a snapshot for deferred deletion:
# storpool snapshot testsnap deleteAfter 1d
OK
The above will set a target delete date for this snapshot in exactly one day from the present time.
Note
The snapshot will be deleted at the desired point in time only if delayed snapshot delete was enabled in the local cluster, check Management configuration for details.
A snapshot could also be bound to its child volumes, it will exist until all child volumes are deleted:
# storpool snapshot testsnap bind
OK
The opposite operation is also possible, to unbind such snapshot:
# storpool snapshot testsnap unbind
OK
To get the space that will be freed if a snapshot is deleted:
# storpool snapshot space
----------------------------------------------------------------------------------------------------------------
| snapshot | on volume | size | rdnd. | stored | used | missing info |
----------------------------------------------------------------------------------------------------------------
| testsnap | testvolume | 100 GiB | 3 | 27 GiB | -135 GiB | 0 B |
| testvolume@3794 | testvolume | 100 GiB | 3 | 27 GiB | 1.9 GiB | 0 B |
| testvolume@3897 | testvolume | 100 GiB | 3 | 507 MiB | 432 KiB | 0 B |
| testvolume@3899 | testvolume | 100 GiB | 3 | 334 MiB | 224 KiB | 0 B |
| testvolume@4332 | testvolume | 100 GiB | 3 | 73 MiB | 36 KiB | 0 B |
| testvolume@4333 | testvolume | 100 GiB | 3 | 45 MiB | 40 KiB | 0 B |
| testvolume@4334 | testvolume | 100 GiB | 3 | 59 MiB | 16 KiB | 0 B |
| frozenvolume | - | 8 GiB | 2 | 80 MiB | 80 MiB | 0 B |
----------------------------------------------------------------------------------------------------------------
Used mainly for accounting purposes. The columns are as follows:
snapshot
Name of the snapshot.
on volume
The name of the volume child for this snapshot if any. For example, a frozen volume would have this field empty.
size
The size of the snapshot as provisioned.
rdnd.
Number of copies for this volume or its erasure coding scheme.
stored
How much data is actually written.
used
Stands for the amount of data that would be freed from the underlying drives (before redundancy) if the snapshot is removed.
missing info
If this value is anything other than
0 B
probably some of thestorpool_controller
services in the cluster are not running correctly.
The used
column could be negative in some cases when the snapshot has more
than one child volume. In these cases deleting the snapshot would “free”
negative space i.e. will end up taking more space on the underlying disks.
Promoting snapshots
A snapshot could also be rebased to root (promoted), or rebased to another parent snapshot in a chain:
# storpool snapshot testsnap rebase # [parent-snapshot-name]
OK
Renaming snapshots
To rename a snapshot:
# storpool snapshot testsnap rename ubuntu1604-base
OK
Attention
Changing the name of a snapshot will not wait for clients that have this snapshot attached to update the name of the symlink. Always use client sync for all clients with the snapshot attached.
Remote snapshots
In case multi-site or multicluster is enabled (the cluster has a
storpool_bridge
service running, see Multi-site and multi-cluster),
a snapshot could be exported and become visible to other configured clusters.
For example, to export a snapshot snap1
to a location named
StorPool-Rome
:
# storpool snapshot snap1 export StorPool-Rome
OK
To list the presently exported snapshots:
# storpool snapshot list exports
-------------------------------------------------------------------------------
| remote | snapshot | globalId | backingUp | volumeMove |
-------------------------------------------------------------------------------
| StorPool-Rome | snap1 | nzkr.b.cuj | false | false |
-------------------------------------------------------------------------------
To list the snapshots exported from remote sites:
# storpool snapshot list remote
------------------------------------------------------------------------------------------
| location | remoteId | name | onVolume | size | creationTimestamp | tags |
------------------------------------------------------------------------------------------
| s02 | a.o.cxz | snapshot1 | | 107374182400 | 2019-08-20 03:21:42 | |
------------------------------------------------------------------------------------------
Single snapshot could be exported to multiple configured locations.
To create a clone of a remote snapshot locally:
# storpool snapshot snapshot1-copy template hybrid-r3 remote s02 a.o.cxz # [tag key=value]
In this example, the remote location
is s02
and the remoteId
is
a.o.cxz
. Any key=value
pair tags may be configured at creation time.
To unexport a local snapshot:
# storpool snapshot snap1 unexport StorPool-Rome
OK
If you need to swam the remote location you can use the all
keyword. The
system will attempt to unexport the snapshot from all location it was previously
exported to.
Note
If the snapshot is presently being transferred then the unexport
operation will fail. It could be forced by adding force
to the end
of the unexport command, however this is discouraged in favor to
waiting for any active transfer to complete.
To unexport a remote snapshot:
# storpool snapshot remote s02 a.o.cxz unexport
OK
The snapshot will no longer be visible with storpool snapshot list remote
.
To unexport a remote snapshot and also set for deferred deletion in the remote site:
# storpool snapshot remote s02 a.o.cxz unexport deleteAfter 1h
OK
This will attempt to set a target delete date for a.o.cxz
in the remote site
in exactly one hour from the present time for this snapshot. If the
minimumDeleteDelay
flag (see Minimum deletion delay) in the
remote site has a higher value (for example, 1 day), the selected value will be
overwritten with the minimumDeleteDelay
- in this example 1 day. For more
information on deferred deletion, see Remote deferred deletion.
Moving snapshots
To move a snapshot to a different cluster in a multi-cluster environment (see Cluster):
# storpool snapshot snap1 moveToRemote Lab-D-cl2
Note
Moving a snapshot to a remote cluster is forbidden for attached snapshots. For more information on snapshot moving, see Moving volumes and snapshots.