snapm - Man Page

Linux snapshot manager

Synopsis

snapm [global_args] snapshot [activate|deactivate|autoactivate|list|show]

snapm [global_args] plugin [list]

snapm snapset create [-b|--bootable] [-r|--revert] [-s|--size-policy policy] name source[size_policy]...

snapm snapset delete [name|uuid] [--name name] [--uuid uuid]

snapm snapset rename old_name new_name

snapm snapset revert [name|uuid] [--name name] [--uuid uuid]

snapm snapset resize [name|uuid] [--name name] [--uuid uuid] [-s|--size-policy policy] source[size_policy]...

snapm snapset split name new_name source...

snapm snapset prune name source...

snapm snapset activate [name|uuid] [--name name] [--uuid uuid]

snapm snapset deactivate [name|uuid] [--name name] [--uuid uuid]

snapm snapset autoactivate [--yes|--no] [name|uuid] [--name name] [--uuid uuid]

snapm snapset list [name|uuid] [--name name] [--uuid uuid] [--nameprefixes] [--noheadings] [--options fields] [--sort fields] [--rows|--json] [--separator separator]

snapm snapset show [name|uuid] [--members] [--name name] [--uuid uuid] [--json]

snapm snapshot activate [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid]

snapm snapshot deactivate [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid]

snapm snapshot autoactivate [--yes|--no] [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid]

snapm snapshot list [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid] [--nameprefixes] [--noheadings] [--options fields] [--sort fields] [--rows|--json] [--separator separator]

snapm snapshot show [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid] [--json]

snapm plugin list [--nameprefixes] [--noheadings] [--options fields] [--sort fields] [--rows] [--separator separator]

Description

Snapm is a snapshot manager for Linux systems. It manages snapshots taken at a common moment in time as a snapshot set ("snapset").

Options

-d|--debug debug_flags: A comma-separated list of subsystem names to enable debugging output for, or 'all' to enable all debugging. The available debug classes are: manager, command, plugins, report.
-h|--help: Display usage information and exit.
-b|--bootable: When creating snapshot sets automatically create a snapshot boot entry for the set.
-n|--name name: Specify a snapset name to operate on.
-N|--snapshot-name name: Specify a snapshot name to operate on.
--members: Include individual snapshots in the output of snapset show commands.
--name-prefixes|--nameprefixes: Add a 'SNAPM_' prefix plus the field name to the output. Useful with --noheadings to produce a list of field=value pairs that can be used to set environment or shell variables.
--no-headings|--noheadings: Suppress output of report headings.
-o|--options fields: Specify which fields to display.
-O|--sort sort_fields: Specify which fields to sort by.
-r|--revert: When creating snapshot sets automatically create a snapshot revert entry for the set.
--rows: Output report columns as rows
--json: Produce show or list output in JSON notation
--separator separator: Report field separator
-s|--size-policy size_policy: Specify a default size policy when creating snapshot sets
-u|--uuid uuid: Specify a snapset uuid to operate on.
-U|--snapshot-uuid uuid: Specify a snapshot uuid to operate on.
-v|--verbose: Increase verbosity level. Specify multiple times, or set additional debug classes with --debug to enable more verbose messages.
-V|--version version: Display the version of snapm and exit.

Snapm manages named collections of snapshots taken at a common point in time as snapshot sets. A snapshot set is created from a list of sources (mount point or block device paths) and allows the state of the system to be captured spanning over several volumes.

Valid characters for snapset names are: a–z A–Z 0–9 + . -

Snapshot sets and snapshots are also identified by a unique UUID value. The terms snapshot set and snapset are used interchangeably in this manual page.

A plugin model is used to map mount points or devices onto possible snapshot providers. A provider plugin must exist for each source path specified when creating a snapshot set. The current plugins support LVM2 copy-on-write, LVM2 thin provisioned and Stratis snapshots.

The snapset subcommand allows snapsets to be created, deleted, enumerated, renamed, reverted, and activated or deactivated.

The snapshot subcommand provides access to information describing individual snapshots that are part of a snapshot set, for example the device path and snapshot status.

Snapshot set and snapshot status

Snapshots from different providers may exist in several possible states: some providers allow snapshots to be in an active or inactive state and snapshots for some providers (for example LVM2 Copy-on-Write snapshots) have a specific size for the snapshot data store. If this space is completely consumed the snapshot becomes invalid and can no longer be accessed.

When a revert is executed for a snapshot set that is currently mounted the status of the snapshot set is reverting. If the snapshot set is in use (either the origin or snapshot volumes are mounted) The revert will take place the next time the volumes making up the snapshot set are activated.

The status of a snapset is an aggregation of the status of the individual snapshots it contains: if any snapshots are inactive then the overall status of the snapset is also inactive. If any snapshots within the set are invalid then the snapshot set status as a whole is also invalid.

Snapshot size policies

An optional size policy hint can be specified when creating a snapshot set, either as a global default or individually for each source path. The policy is used at creation time to check that sufficient space is present.

For snapshot providers that require a fixed space to be allocated for the snapshot the policy is used to determine the size of the snapshot backing store.

There are currently four types of size policy that can be used to specify the space required:

FIXED: A fixed size with optional unit suffix (MiB, GiB, TiB, etc.).
%FREE: A percentage of the free space available from 0 to 100%.
%USED: A percentage of the space currently consumed on the mount point, as reported by df. Values greater than 100% can be used to allow the existing content to be completely overwritten without running out of space. This policy can only be applied to snapshot sources that correspond to mounted file systems.
%SIZE: A percentage of the size of the origin volume from 0 to 100%.

The default size policy mounted volumes if none is specified is 200%USED. The default size policy for unmounted block devices is 25%SIZE.

Snapshot Set Commands

snapm snapset create [-b|--bootable] [-r|--revert] [-s|--size-policy policy] name source[size_policy]...
Create a new snapshot set using the specified list of mount points and block devices.

The newly created snapset is displayed on the terminal on success:

# snapm snapset create backup / /home /var /opt /srv
SnapsetName: backup
Sources: /, /home, /var, /opt, /srv
NrSnapshots: 5
Time: 2024-12-05 17:46:12
UUID: 87c89914-51a5-5043-8513-667100213243
Status: Inactive
Autoactivate: no
Bootable: no

When creating snapshot sets --bootable and --revert can optionally be used to automatically create snapshot boot and revert boot entries respectively.

A size policy can be specified on the create command line, either as a global default or individually for each source path. To specify a default policy use the --size-policy argument. To specify a per-source path size policy append the policy to the source path separated by the : character:

# snapm snapset create backup --size-policy 25%FREE /:4G /home /var
SnapsetName: backup
Sources: /, /home, /var
NrSnapshots: 3
Time: 2024-12-05 17:47:19
UUID: 4106d5b5-b521-504d-8822-8826594debb5
Status: Inactive
Autoactivate: no
Bootable: no

Snapshot providers that do not allocate a fixed size for snapshot data will check for available space according to the policy at creation time but do not enforce a fixed size for individual snapshots: space is allocated from the available pool on an as-needed basis.

snapm snapset delete [name|uuid] [--name name] [--uuid uuid]
Delete the specified snapset. The snapset to delete may be specified either by its name or uuid.

snapm snapset rename old_name new_name
Rename an existing snapset. The snapset to be renamed is specified as old_name and the new name is given as new_name.

snapm snapset revert [name|uuid] [--name name] [--uuid uuid]
Revert an existing snapset, re-setting the content of the origin volumes to the state they were in at the time the snapset was created. The snapset to be reverted may be specified either by its name or uuid.

Rolling back a snapshot set with mounted and in-use origin volumes will schedule the revert to take place the next time that the volumes are activated, for example by booting into a configured revert boot entry for the snapshot set.

snapm snapset resize [name|uuid] [--name name] [--uuid uuid] [-s|--size-policy policy] source[size_policy]...
Resize the members of an existing snapshot set, re-applying size policies to one or more of the snapshots making up the set. The snapshot set to resize may be specified by either its name or uuid.

For snapshot providers that require a fixed space to be allocated to the snapshot this command will physically resize the corresponding snapshot according to the given size policy (lvm2cow). For snapshot providers that dynamically allocate space the command will check that the requested space is available at the time of the resize command. An error is returned if the specified size policies cannot be satisfied.

Size policies may be specified on a per-source basis using the same syntax as the snapset create command. A default size policy can be set using the --size-policy argument. If no source paths are specified the command applies the default size policy to each member of the snapshot set.

snapm snapset split name new_name source...
Split snapshots from an existing snapshot set into a new snapshot set.

Split the snapshot set named name into a new snapshot set named 'new_name'. Each listed source from 'name' is split into the new snapshot set. Sources that are not listed on the command line remain part of the original snapshot set. It is an error to split all sources from a snapshot set: in this case use 'snapm snapset rename' instead.

snapm snapset prune name source...
Prune snapshots from an existing snapshot set.

Prune the listed sources from the snapshot set named name. The listed snapshot sources are pruned from the snapshot set and permanently deleted. Care should be taken since this operation cannot be reversed. It is an error to prune all sources from a snapshot set: in this case use 'snapm snapset delete' instead.

snapm snapset activate [name|uuid] [--name name] [--uuid uuid]
Attempt to activate snapshots making up snapsets. If no argument is given the command will attempt to activate all snapshots of all snapsets present on the system. If a name or uuid is specified then only that snapset will be activated.

Not all snapshot providers support optional activation for snapshot volumes: for these providers activate and deactivate have no effect on volume availability.

snapm snapset deactivate [name|uuid] [--name name] [--uuid uuid]
Attempt to deactivate snapshots making up snapsets. If no argument is given the command will attempt to deactivate all snapshots of all snapsets present on the system. If a name or uuid is specified then only that snapset will be deactivated.

Not all snapshot providers support optional activation for snapshot volumes: for these providers activate and deactivate have no effect on volume availability.

snapm snapset autoactivate [--yes|--no] [name|uuid] [--name name] [--uuid uuid]
Enable or disable snapshot autoactivation for snapsets matching selection criteria. Some snapshot providers (lvm2-thin) support optional snapshot volume activation when activating resources for e.g. at boot time. The snapset autoactivate subcommand allows control of this behaviour for snapshot sets managed by snapm.

snapm snapset list [name|uuid] [--name name] [--uuid uuid] [--nameprefixes] [--noheadings] [--options fields] [--sort fields] [--rows|--json] [--separator separator]
Output a tabular report of snapsets.

Displays a report with one snapset per line, containing fields describing the properties of the configured snapshot sets.

The list of fields to display is given with -o|--options as a comma separated list of field names. To obtain a list of available fields run 'snapm snapset list -o help'. If the list of fields begins with the '+' character the specified fields are appended to the default field list. Otherwise the given list of fields replaces the default set of report fields.

The --rows, --noheadings, and --nameprefixes options can be used to generate output in a machine readable form, suitable for setting shell or environment variables.

Report output may be sorted by multiple user-defined keys using the --sort option. The option expects a comma separated list of keys, with optional + and - prefixes indicating ascending and descending sort for that field respectively.

snapm snapset show [name|uuid] [--members] [--name name] [--uuid uuid] [--json]
Display snapsets matching selection criteria on standard out. If the --members option is given individual snapshots are included in the output.

Snapshot Commands

snapm snapshot activate [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid]
Attempt to activate individual snapshots matching selection criteria. If no argument is given the command will attempt to activate all snapshots of all snapsets present on the system. If a snapshot or snapset name or uuid is specified then only matching volumes will be activated.

Not all snapshot providers support optional activation for snapshot volumes: for these providers activate and deactivate have no effect on volume availability.

snapm snapshot deactivate [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid]
Attempt to deactivate individual snapshots matching selection criteria. If no argument is given the command will attempt to deactivate all snapshots of all snapsets present on the system. If a snapshot or snapset name or uuid is specified then only matching volumes will be deactivated.

Not all snapshot providers support optional activation for snapshot volumes: for these providers activate and deactivate have no effect on volume availability.

snapm snapshot autoactivate [--yes|--no] [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid]
Enable or disable snapshot autoactivation for individual snapshots matching selection criteria. Some snapshot providers (lvm2-thin) support optional snapshot volume activation when activating resources for e.g. at boot time. The snapshot autoactivate subcommand allows control of this behaviour for individual snapshots managed by snapm.

snapm snapshot list [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid] [--nameprefixes] [--noheadings] [--options fields] [--sort fields] [--rows|--json] [--separator separator]
Output a tabular report of snapshots.

Displays a report with one snapshot per line, containing fields describing the properties of the configured snapshots.

The list of fields to display is given with --options as a comma separated list of field names. To obtain a list of available fields run 'snapm snapshot list -o help'. If the list of fields begins with the '+' character the specified fields are appended to the default field list. Otherwise the given list of fields replaces the default set of report fields.

The --rows, --noheadings, and --nameprefixes options can be used to generate output in a machine readable form, suitable for setting shell or environment variables.

snapm snapshot show [name|uuid] [--name name] [--uuid uuid] [--snapshot-name name] [--snapshot-uuid uuid] [--json]
Display snapshots matching selection criteria on standard out.

Plugin Commands

snapm plugin list [--nameprefixes] [--noheadings] [--options fields] [--sort fields] [--rows] [--separator separator]
Output a tabular report of plugins.

Displays a report with one plugin per line, containing fields describing the properties of the available plugins.

The list of fields to display is given with --options as a comma separated list of field names. To obtain a list of available fields run 'snapm plugin list -o help'. If the list of fields begins with the '+' character the specified fields are appended to the default field list. Otherwise the given list of fields replaces the default set of report fields.

The --rows, --noheadings, and --nameprefixes options can be used to generate output in a machine readable form, suitable for setting shell or environment variables.

Booting and Rolling Back Snapshot Sets

Snapshot manager integrates with the boom(8) boot manager to facilitate booting and rolling back snapshot sets. Specifying the -b|--bootable or -r|--revert arguments when creating a snapshot set will cause snapm to create a snapshot boot or revert boot entry respectively. In order for a snapshot set to be made with boot or revert support it must include a snapshot of the root filesystem.

The snapshot boot entry allows the system to boot into the state of the system at the time the snapshot was created. This can be used to inspect the previous state of the system or to quickly recover from a failed update or reconfiguration.

In order to reset the system back to the state at the time the snapshot set was created the revert boot entry is used after issuing a snapm snapset revert command. After running the revert command the system should be rebooted into the revert boot entry. This will start the revert operation on all affected volumes.

Note that rolling back a snapshot set will also destroy the snapshot set since the snapshot volumes are folded back into the origin devices. Following the revert the snapshot set will no longer appear in the output of snapm snapset list or snapm snapset show commands.

Reporting Commands

Both the snapset list and snapshot list commands use a common reporting system to display the results of the query. The selection of fields, and the order in which they are displayed may be controlled to produce custom report formats using the -o/--options argument. The report output can also be optionally sorted by one or more field values using the -O/--sort argument.

To display the available fields for a given report type use the special field name help:
# snapm snapset list -o help
Snapshot set Fields
-------------------
name - Snapshot set name [str]
uuid - Snapshot set UUID [uuid]
timestamp - Snapshot set creation time as a UNIX epoch value [num]
time - Snapshot set creation time [time]
nr_snapshots - Number of snapshots [num]
sources - Snapshot set sources [strlist]
mountpoints - Snapshot set mount points [strlist]
devices - Snapshot set devices [strlist]
status - Snapshot set status [str]
autoactivate - Autoactivation status [str]
bootable - Configured for snapshot boot [str]
bootentry - Snapshot set boot entry [sha]
revertentry - Snapshot set revert boot entry [sha]

Report Fields

The snapm reports provide several types of field that may be added to the default field set for either snapset or snapshot reports, or used to create custom reports.

Snapshot sets

Snapshot set fields provide information about snapsets as a whole, including the name, number of snapshots, mount points, status and UUID.

name: The name of this snapshot set.
uuid: The UUID of this snapshot set.
timestamp: The snapshot set creation time as a UNIX epoch value.
time: The snapshot set creation time as a human readable string.
nr_snapshots: The number of snapshots contained in this snapshot set.
sources: The list of sources (devices or mount points) contained in this snapshot set.
mountpoints: The list of mount points contained in this snapshot set.
devices: The list of block devices contained in this snapshot set.
status: The current status of this snapshot set. Possible values are Active, Inactive, and Invalid.
autoactivate: The autoactivation setting for this snapshot set.
bootentry: The boot identifier of the boot loader entry configured to boot this snapshot set, or the empty string if no boot entry has been created.
revertentry: The boot identifier of the boot loader entry configured to revert this snapshot set following a merge operation, or the empty string if no revert boot entry has been created.

Snapshots

Snapshot fields provide information about the snapshots that make up snapsets, including the fields available in the snapset report as well as fields specific to individual snapshots.

snapshot_name: The provider-specific name used to refer to the snapshot.
snapshot_uuid: The snapshot UUID.
origin: The origin volume that this snapshot refers to.
mountpoint: The path to the mount point where this snapshot was taken from.
devpath: The provider-specific path to the device used to mount this snapshot.
provider: A string representing the snapshot provider plugin used to create this snapshot.
status: The current status of this snapshot. Possible values are Active, Inactive, and Invalid.
size: The size of the snapshot as a human readable string.
free: The amount of free space available to the snapshot as a human readbale string.
size_bytes: The size of the snapshot in bytes.
free_bytes: The amount of free space available to the snapshot in bytes.
autoactivate: Whether this snapshot is configured for autoactivation.

JSON output

Reports can optionally be output in JSON notation by using the --json argument.

Examples

List the available snapshot sets
# snapm snapset list
SnapsetName Time NrSnapshots Status Sources
backup 2024-12-05 17:53:10 4 Active /, /opt, /srv, /var
userdata 2024-12-05 17:53:22 2 Inactive /data, /home

List the available snapshots
# snapm snapshot list
SnapsetName Name Origin Source Status Size Free Autoactivate Provider
backup fedora/root-snapset_backup_1733421190_- /dev/fedora/root / Active 8.8GiB 8.8GiB yes lvm2-cow
backup fedora/var-snapset_backup_1733421190_-var /dev/fedora/var /var Active 6.4GiB 6.4GiB yes lvm2-cow
backup p1/fs2-snapset_backup_1733421190_-srv /dev/stratis/p1/fs2 /srv Active 2.0GiB 3.2GiB yes stratis
backup p1/fs1-snapset_backup_1733421190_-opt /dev/stratis/p1/fs1 /opt Active 1.0GiB 3.2GiB yes stratis

Create a new snapshot set from the mount points /, /home, and /var
# snapm snapset create backup / /home /var
SnapsetName: backup
Sources: /, /home, /var
NrSnapshots: 3
Time: 2024-12-05 17:57:05
UUID: b9b4cd96-75a5-5826-a26b-b617c06bd877
Status: Active
Autoactivate: no
Bootable: no

Create a bootable snapshot set from the mount points /, /home, and /var
# snapm snapset create -br upgrade / /home /var
SnapsetName: upgrade
Sources: /, /home, /var
NrSnapshots: 3
Time: 2024-12-05 17:58:37
UUID: 1a2b5bc4-e123-5553-a4a3-6ba798baa945
Status: Active
Autoactivate: yes
Bootable: yes
BootEntries:
SnapshotEntry: f3a98eb
RevertEntry: 79bfab1

Delete the snapset named 'backup'
# snapm snapset delete backup

Activate all snapshot sets with verbose output
# snapm -v snapset activate
INFO - Activated 2 snapshot sets

Rename the snapset 'backup' to 'oldbackup'
# snapm snapset rename backup oldbackup

Display the snapset named 'upgrade'
# snapm snapset show upgrade
SnapsetName: upgrade
Sources: /, /var, /home
NrSnapshots: 3
Time: 2024-12-05 17:58:37
UUID: b5752dfa-b3a0-5a1d-ab1d-0cab2c41e0c9
Status: Active
Autoactivate: yes
Bootable: no

Display the snapshot with UUID b201bdba-89b7-5014-a80d-f5d4b9a690ed
# snapm snapshot show -U b201bdba-89b7-5014-a80d-f5d4b9a690ed
Name: fedora/home-snapset_upgrade_1733421517_-home
SnapsetName: upgrade
Origin: /dev/fedora/home
Time: 2024-12-05 17:58:37
Source: /home
MountPoint: /home
Provider: lvm2-thin
UUID: b201bdba-89b7-5014-a80d-f5d4b9a690ed
Status: Active
Size: 1.0GiB
Free: 1.9GiB
Autoactivate: yes
DevicePath: /dev/fedora/home-snapset_upgrade_1733421517_-home
VolumeGroup: fedora
LogicalVolume: home-snapset_upgrade_1733421517_-home

Authors

Bryn M. Reeves <bmr@redhat.com>

Info

Dec 05 2024 Linux MAINTENANCE COMMANDS

snapm - Man Page

Synopsis

Description

Options

Snapshot Sets and Snapshots

Booting and Rolling Back Snapshot Sets

Reporting Commands

Report Fields

Snapshot sets

Snapshots

JSON output

Examples

Authors

See Also

Info