SNAPM(8)

NAME
Snapm — Linux snapshot manager

SYNOPSIS
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm
snapm

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.

SNAPSHOT SETS AND SNAPSHOTS
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
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
Delete the specified snapset. The snapset to delete may be specified either by its name or uuid.

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

snapm
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
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
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
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
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
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
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
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
Display snapsets matching selection criteria on standard out. If the --members option is given individual snapshots are included in the output.

Snapshot Commands

snapm
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
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
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
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. 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
Display snapshots matching selection criteria on standard out.

Plugin Commands

snapm
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. 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.

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>

SEE ALSO
boom(8)
Snapm project page: https://github.com/snapshotmanager/snapm
Boom project page: https://github.com/snapshotmanager/boom
LVM2 resource page: https://www.sourceware.org/lvm2/
Stratis resource page: https://stratis-storage.github.io/