Your First Snapshot Set

2026-01-20T00:00:00+00:00

Your First Snapshot Set</h1>
A snapshot set is a collection of snapshots, bound together with a name, and created at a common point in time 1</a>. At a bare minimum, to create one, you just need a name and a list of sources (mount points or block devices) that you would like to include in the set. More advanced options exist to give additional control over the creation process and the resulting snapshot set: we will cover these in detail in future blog posts.

Choosing Sources: First Things to know</h2>
Before you can create your first snapshot set you'll need to ensure that you have everything necessary in place:

You need snapshot capable storage: LVM2 regular or thin provisioned volumes, or Stratis file systems. </li>

You need free space for your snapshots to use (either in an LVM2 volume group with regular volumes, or in the thin pool containing the volumes with LVM2 Thin provisioning or Stratis storage). </li>

You'll need to know the mount point or block device path for the volumes you wish to include in your snapshot set. </li>

You need `snapm</code>. </li> </ul>`
`For your first experiment, it doesn't matter what you snapshot as long as it meets these criteria. Later, when you are using the tool in anger, you can craft specific commands for different use cases or automate the process via schedules. To get the most from this exercise, it is helpful to be able to make some changes to whatever you snapshot so you'll have genuine differences to examine.`
`If you haven't already installed the snapm</code> command on your system read` `Getting snapm</code></a> and follow the instructions there: then return here to continue.`
Sources for Snapshot Manager can be either mount points, or block devices. A mount point source corresponds to a mounted file system. You can specify it either by mount point path (for example, /home</code>) or by the underlying block device path (for example, /dev/vg0/home</code>). A block device source is a block device that is not mounted and that need not contain a mountable file system image (for example, databases, virtual machine images, and other non file system content).
`Snapshot Manager uses the mechanism of provider plugins to support different types of storage. A provider plugin corresponds to a particular storage technology (LVM2 CoW, LVM2 Thin, Stratis, and so on). The snapm</code> command will determine the correct plugins to use for any given source (assuming that one exists and is able to snapshot the requested volume) — you do not need to specify which plugins to use on the command line.`
`Some familiarity with your storage stack's management tools will help when it comes to planning, monitoring, and finding your way around (whether that's` `vgs(8)</code></a>, lvs(8)</code></a>, et al. for LVM2, or the stratis(8)</code></a> command line tool for Stratis storage). Knowledge of common Linux administrative tools like the mount(8)</code></a> program, findmnt(8)</code></a>, lsblk(8)</code></a>, and blkid(8)</code></a> will also be an advantage — refer to the respective manual pages for more details, or check out one of the many great Linux systems administration tutorials available on the internet.`
Naming Your Snapshot Set</h2> You are free to name your snapshot set anything you like within the constraints enforced by snapm</code> and its provider plugins: The _</code> (underscore) character is not permitted. </li> The valid characters for snapshot set names are the ASCII lowercase and uppercase alphabetic characters, the digits, and the symbols .</code>, +</code>, and -</code>. </li> Certain strings may be forbidden by particular provider plugins: for instance, LVM2 reserves the string _mlog</code> (and others) for internal logical volume names (refer to lvm(8)</code></a>, lvmraid(7)</code></a> and related manual pages for more information). </li> Certain providers may enforce a maximum name length, for example, for LVM2 volumes this is 127 characters. Note that this limit includes parts of the internal name generated by snapm</code> (which varies according to the mount point the snapshot refers to), so the usable name length is somewhat shorter. Nobody likes long device names anyway so this should not be a concern in most situations. </li> Any provider that represents the snapshot name as an entry in the file system (which includes all current and planned snapshot providers) is naturally limited by the maximum allowed file name length on Linux (255 characters). Again, this absolute maximum is reduced somewhat by the need for snapm</code> to encode various information into the names it generates. </li> If you include a .</code> followed by a nonnegative number at the end of your snapshot set name snapm</code> will consider it to be an index. This is useful when taking recurring snapshots sets of the same things with a common base name. You can also have snapm</code> add one automatically using the --autoindex</code> option (more on that in a later post). </li> it is generally best to not include a date or time reference in the name unless you really, really want to: snapm</code> already stores the creation time of the snapshot set as a UNIX epoch timestamp value and renders it as human readable date and time strings in the local time zone. </li> The name .</code> is reserved by snapm for referencing the live root file system. </li> </ol> Aim for memorable and meaningful names: quux-foo-backup</code> might seem like a good idea at the time, when you're typing in a hurry, but future you will thank present you for coming up with something more self-explanatory. Good names might be: before-upgrade</code> </li> after-upgrade</code> </li> pre-deployment</code> </li> post-deployment</code> </li> hourly.N</code> (where N</code> is an integer uniquifying index either appended manually or enabled automatically with --autoindex</code> - see snapm(8)</code>) </li> </ul> Bad names would include: backup</code> </li> thing</code> </li> thisone</code> </li> thatone</code> </li> something-something-something-snapshot-side</code> </li> foo</code>, fubar</code>, plugh</code>, quux</code>, qwerty</code>, thud</code>, xyzzy</code>, etc. </li> </ul> Overriding The Default Size Policy</h2> Snapshot Manager provides size policies that allow the user to request that a certain amount of space be available when creating snapshots. For some providers (LVM2 Thin, Stratis) this is simply a check that this space is available at the time the snapshot set is created. For LVM2 CoW it determines the actual size of the snapshot exception store that the tool will allocate. The default size policy is different depending on whether you are creating a snapshot from a mount point source or a block device source. For mount points the default size policy specifies twice the space currently used on the mount point (200%USED</code> in size policy notation). For block devices it is one quarter the physical size of the device (25%SIZE</code>). To override these defaults, either append a colon and size policy to individual sources (:POLICY</code>) or use --size-policy=POLICY</code> for all sources without explicit policies. For example: /:2GiB</code> — specify a source of /</code> (the root file system) with a fixed 2GiB size policy </li> /:100%SIZE /home:50%SIZE</code> — specify sources for root and home with a policy requesting 100% and 50% of their respective device sizes </li> --size-policy=100%SIZE</code> — set the policy for all sources not otherwise specified on the command line to be 100% of the corresponding device size </li> </ul> The snapm snapset create</code> command</h2> With the basics explained it's time to actually create a snapshot set with the snapm snapset create</code> command. Take your chosen name and list of sources and append them to the command line, then hit Enter to run the program and create the snapshot set: # snapm snapset create my-first-set / /var SnapsetName: my-first-set Sources: /, /var NrSnapshots: 2 Time: 2026-01-13 12:44:12 UUID: 0ea16412-8ceb-59d4-af0b-9afa79d306e9 Status: Inactive Categories: daily, hourly Autoactivate: no OriginMounted: yes Mounted: no Bootable: no </code></pre> That's all there is to it! Before we conclude let's take a brief look at the output the tool produces: SnapsetName</code> — the name you gave to the snapshot set </li> Sources</code> — the list of sources (minus any size policy that was specified on the command line) </li> NrSnapshots</code> — the number of snapshots contained in this set </li> Time</code> — the time and date the snapshot set was created in your local time zone </li> UUID</code> — a unique identifier for the snapshot set (a Version 5 UUID to be exact^{2</a>) </li>} Status</code> — the status of this snapshot set: one of Active</code>, Inactive</code>, Invalid</code>, or Reverting</code>) </li> Categories</code> — the timeline categories that this snapshot set belongs to: we will cover timeline categories, scheduling, and automatic garbage collection in a future blog post. </li> Autoactivate</code> — whether automatic boot time activation is enabled for this snapshot set: yes</code> or no</code> </li> OriginMounted</code> — the mount status of this snapshot set's origin devices: yes</code> or no</code> </li> Mounted</code> — the mount status of this snapshot set: yes</code> or no</code> </li> Bootable</code> — whether this snapshot set has boom(8)</code></a> boot entries or not: yes</code> or no</code> </li> </ul> We will get to all of these properties and their precise meaning in good time, but for now the Status</code> field deserves a little more explanation: some snapshot providers (LVM2 Thin, Stratis) support optional activation for snapshot devices. This means that you don't have snapshot devices cluttering the system and using resources when they are not required and is therefore more efficient — especially when dealing with very large numbers of snapshots. For LVM2 CoW the snapshot volume must be active at all times that the origin is active. If your snapshot set includes thin snapshots (LVM2 Thin or Stratis) then it will begin its life in the Inactive</code> state3</a>. If it only includes LVM2 CoW snapshots then it will begin in the Active</code> state (and cannot, in fact, become Inactive</code> unless the origin volume is also inactive). If you receive an error message instead of the expected output shown above study it carefully to try to understand what it is telling you. Most error conditions have a clear message that explains exactly what is wrong. The most common error is ‘not enough space’: if you run into this you will see a message like this rather than the snapshot set summary: # snapm snapset create my-first-set / /var ERROR - Error creating lvm2-cow snapshot: Volume group fedora has insufficient free space to snapshot / (14.5GiB < 15.1GiB) ERROR - Command failed: Insufficient free space for snapshot set my-first-set </code></pre> If this happens you can resolve the problem in one of these three ways: Add more space to the volume group or thin pool </li> Delete one or more unneeded volumes to reclaim space </li> Change the size policy to create a smaller snapshot </li> </ul> If you receive some other error refer to the snapm(8)</code> manual page and the FAQ</a>: you may find that your problem already has a straightforward answer. If not then you can reach out to your distribution's support channels or the developers for assistance4</a>. Care and Feeding of Your Snapshot Set</h2> Now that you have a snapshot set that captures the state of your system at some moment in time you need to know how to look after it. This is essentially the same task as you would need to carry out for any other volume managed with your tool of choice. The major point to bear in mind is that both thin and LVM2 CoW snapshots can run out of space. It is important to ensure that this does not happen for the reasons explained in the Performance & Safety section of the Snapshot Manager FAQ</a>. As an example, using the snapshot set created in the previous step we see the following output when running the lvs(8)</code></a> program5</a>: # lvs -o lv_name,lv_size,data_percent LV LSize Data% root 10.00g root-snapset_my-first-set_1768308252_- 1.00g 0.19 swap 512.00m var 12.00g var-snapset_my-first-set_1768308252_-var 1.20g 0.19 </code></pre> Note the 0.19% value in the Data%</code> column: this is the percentage of the snapshot exception store that has been used so far. In this case it's a very healthy value. If the value begins to approach 100% you need to take action using lvresize(8)</code></a> or snapm snapset resize</code> in order to avoid the snapshot being invalidated. We will discuss more comprehensive monitoring and maintenance strategies in later blog updates. For now, you can use your regular storage administration tools (whether that is lvs(8)</code></a> for LVM2 volumes, or the stratis(8)</code></a> command for Stratis storage), or the snapm snapshot list</code> command to keep an eye on the space available to your snapshots. You can resize individual snapshots using the corresponding tool (for example, lvresize(8)</code></a> for LVM2), or you can use the snapm snapset resize</code> command to apply new size policies to an already created snapshot set. Visualizing Changes</h2> Before we conclude let's take a look at some of the advanced features in recent versions of snapm</code>. For this part of the exercise, it helps if you can make some small change to the system. We will assume that your snapshot set included the root file system in this example but if that isn't the case you can adjust the paths used accordingly. We suggest creating a single new file — something simple made with the echo</code> command is fine for our purposes: # echo "Something changed!" > /etc/my-new-file.conf </code></pre> Now that you have a definitive change in the file system state, use the snapm snapset diff</code> command to view it: # snapm snapset diff my-first-set . -s /etc -i /etc/my-new-file.conf Gathering paths from my-first-set /etc: found 1879 paths Scanned 1879 paths in 0:00:00.784354 (excluded 0) Gathering paths from System Root /etc: found 1880 paths Scanned 1880 paths in 0:00:00.539372 (excluded 0) Found 7 differences in 0:00:00.012717 Found 0 moves in 0:00:00.004574 Saved 7 records to diffcache in 0:00:00.014500 Built tree with 7 nodes / └── [] etc └── [+] my-new-file.conf </code></pre> Note that my-new-file.conf</code> appears with the [+]</code> annotation (in green if your terminal supports color output) indicating that it is a new file system entry added since my-first-set</code> was created. To see the exact change in the file content you can use the -o/--output-format diff</code> option of the snapm snapset diff</code> command: # snapm snapset diff my-first-set . -o diff -s /etc -i /etc/my-new-file.conf Loaded 1 records from diffcache in 0:00:00.000226 Found 1 content differences diff a/etc/my-new-file.conf b/etc/my-new-file.conf new file mode 0o100644 --- /dev/null +++ b/etc/my-new-file.conf 2026-01-20 16:59:42.257636 @@ -0,0 +1 @@ +Something changed! </code></pre> There are two key details to notice here: The -o diff</code> output is displayed in unified diff format (again with color coding if your terminal supports that)</li> The results appear quickly when the second command is run. This is because the differences from the first run are cached and reused.</li> </ul> To see all the differences found between the snapshot set and the live system, remove the -i /etc/my-new-file.conf</code> argument and run the command again: # snapm snapset diff my-first-set . -s /etc Gathering paths from my-first-set /etc: found 1879 paths Scanned 1879 paths in 0:00:00.662213 (excluded 0) Gathering paths from System Root /etc: found 1880 paths Scanned 1880 paths in 0:00:00.527266 (excluded 0) Found 7 differences in 0:00:00.012590 Found 0 moves in 0:00:00.004542 Saved 7 records to diffcache in 0:00:00.014054 Built tree with 7 nodes / └── [] etc ├── lvm │ ├── [] archive │ │ ├── [-] fedora_00018-1908271671.vg │ │ └── [+] fedora_00028-486902226.vg │ └── [] backup │ └── [*] fedora └── [+] my-new-file.conf </code></pre> Note that in this example we see changes in the /etc/lvm</code> directory: we are using LVM2 on this system and this is a natural consequence of LVM2's default metadata archival and backup settings. Do not be concerned if you see similar changes on your system when trying this out. In this example we also see that the cache is not used - this is because the new snapset diff</code> command is using different options. Conclusion</h2> That's it for now! We will look at more advanced uses of snapm</code> and the full set of Difference Engine features in future blog posts. In the meantime check out the snapm(8)</code> manual page and the User Guide</a> if this post whetted your appetite for more Snapshot Manager features! If you would like to clean up and remove the snapshot set on your system, use the snapm snapset delete</code> command: # snapm snapset delete my-first-set </code></pre> The snapshots making up a set are created sequentially, since there is presently no interface in Linux for creating multiple snapshots simultaneously. For this reason the individual snapshots will all have very slightly different timestamps. Snapshot Manager quantises these timestamps to provide a single unambiguous creation time for the set as a whole. ↩</a> </li> https://en.wikipedia.org/wiki/Universally_unique_identifier#Versions_3_and_5_(namespace_name-based) ↩</a> </li> Unless creating bootable snapshot sets, in which case autoactivate is always enabled and the set will start out in the Active</code> state (We will cover bootable snapshot sets in detail in a future post). ↩</a> </li> https://github.com/snapshotmanager/snapm/issues/ ↩</a> </li> We are using the lvs</code> program's -o/--options</code> argument here to make sure the displayed fields fit on the page. By default you will see more columns in the tool output. ↩</a> </li> </ol> </section>

Snapshot Manager how-to/walkthrough

2025-12-22T00:00:00+00:00

User Guide

This guide provides user documentation for the snapshot manager (snapm) tool.

Overview

Snapshot manager (snapm) is a tool for managing coordinated sets of snapshots on Linux systems. The snapm tool allows snapshots of multiple volumes to be captured at the same time, representing the system state at the time the snapshot set was created. The tool has a modular plugin architecture allowing different snapshot backends to be used together. Currently snapshots using LVM2 copy-on-write as well as thinly provisioned snapshots using both LVM2 and Stratis are supported.

Key Concepts

Snapshot Sets</h3>
Snapshot manager groups snapshots taken at the same moment in time into a named "snapshot set", or snapset. This allows the snapshots to be managed as a single unit and simplifies the management of snapshots of multiple volumes. Each snapshot set must contain at least one snapshot.

Size Policies</h3>
Size policies control the size of fixed-sized snapshots and check for available space when creating a snapshot set. Some snapshot implementations (Lvm2CoW) require a fixed size to be specified for the snapshot backstore when the snapshot is created. The default size allocated by snapshot manager is 2x the current file system usage, allowing the existing content of the volume to be overwritten twice before exhausting the snapshot space. Plugins for snapshot providers that do not require a fixed snapshot size will check that space is available for the requested size policy at snapshot set creation time.
Available size policies:

FIXED - a fixed size given on the command line</li>
FREE - a percentage fraction of the free space available</li>
USED - a percentage fraction of the space currently used on the mount point (may be greater than 100%)</li>
SIZE - a percentage fraction of the origin device size from 0 to 100%</li> </ul>
The FIXED size policy accepts optional units of KiB, MiB, GiB, TiB, PiB, EiB and ZiB. Units may be abbreviated to the first character.
The USED size policy can only be applied to mounted file systems.
Difference Engine
The Difference Engine is a core facility in `snapm</code> that allows for detailed comparisons between two snapshot sets, or between a snapshot set and the currently running system.`
`How it Works`
`The engine operates by recursively walking the file system trees of both the source and target. It performs a multi-stage analysis to identify changes:`
</li> </ul>
Entry Detection: Identifies files, directories, and symlinks that have been added, removed, or modified.

</li> </ul>
Move Detection: By matching content hashes, the engine can identify files that have been renamed or moved between directories rather than simply being deleted and recreated.

</li> </ul>
Metadata Analysis: Detects changes in file permissions (mode), ownership (UID/GID), and extended attributes (xattrs).

</li> </ul>
Content Comparison: Performs deep content comparisons for regular files, including generating standard unified diffs for text files.
Output Formats and Use Cases
The Difference Engine supports several output formats via the `snapset diff</code> --output-format</code> argument, each suited to different tasks:`
</li> </ul> paths: Useful for scripting, allowing you to pipe a list of changed files to other tools like tar</code> or rsync</code>. </li> </ul> full: Provides a detailed report including old and new file attributes (permissions, ownership, size, modification time) for every change. </li> </ul> short: A concise summary listing the change status code and path for each modified file. </li> </ul> json: Outputs the complete difference data as a JSON object, suitable for parsing by external tools and automation scripts. </li> </ul> diff: Generates a standard unified diff of content changes for modified files. This format is useful for generating patches or detailed content review. </li> </ul> summary: Brief summary of the count of different change types. Change types are colorized using the same coding as tree</code> output. </li> </ul> tree: (Default) Displays changes in a hierarchical tree structure, similar to the standard tree</code> command but annotated with change status. In addition differences can be reported in a tabular format using the standard snapm</code> reporting mechanism using the snapset diffreport</code> command. The available diffreport</code> report output fields are: path: Difference path (string)</li> type: Difference type (string)</li> size_delta: Diff size change (size)</li> content: Content changed (string)</li> metadata: Metadata changed (string)</li> mode_old: Old path mode (string)</li> mode_new: New path mode (string)</li> category: File category (string)</li> movedfrom: Move source (string)</li> movedto: Move destination (string)</li> diffsummary: Summary of content differences (string)</li> hash_old: Old file content hash (string)</li> hash_new: New file content hash (string)</li> filetype: File type (string)</li> mtime_old: Old modification time (time)</li> mtime_new: New modification time (time)</li> </ul> Comparison Modes</h3> You can fine-tune the comparison using various flags: </li> </ul> Content-Only (-c</code>): Ignores all metadata changes and only reports files where the actual data has changed. </li> </ul> Ignore Options: Use --ignore-timestamps</code>, --ignore-permissions</code>, or --ignore-ownership</code> to filter out "noise" during comparisons. Performance and the Diff Cache Walking large file systems and computing content hashes can be resource-intensive. To improve performance, snapm</code> implements a diffcache. </li> </ul> How it works: When a comparison is performed, the results are compressed and stored in /var/cache/snapm/diffcache</code>. </li> </ul> Cache Reuse: Subsequent diff</code> or diffreport</code> commands between the same two sets will load the results from the cache instead of re-scanning the file systems. </li> </ul> Expiry: By default, cache entries expire after 15 minutes. This ensures that results remain fresh if the running system (.</code>) is one of the comparison targets. Use --cache-expires=EXPIRES_SECS</code> to override the default value (900s). </li> </ul> Manual Control: You can override the expiry or disable the cache entirely using the --cache-mode={auto,never,always}</code> and --cache-expires=EXPIRES_SECS</code> options. These options are mutually exclusive. Command Reference</h2> The snapm</code> Command</h3> The snapm</code> command provides the CLI interface to the snapshot manager. It is able to create, delete, and display snapshots and snapshot sets and provides reports listing the snapshots, snapshot sets, and schedules available on the system. Each snapm command operates on a particular object type: a snapshot set, an individual snapshot, or a schedule. snapm snapset <command> <options> # snapset command </code></pre> snapm snapshot <command> <options> # snapshot command </code></pre> Snapset Commands</h2> The snapset</code> subcommand is used to create, delete, rename, activate, deactivate, list and display snapshot sets. snapset create Create a new snapshot set with the provided name and list of sources (mount point or block device paths): snapm snapset create [-b|--bootable] [-r|--revert] [--size-policy policy] <name> <source> [<source> ...] </code></pre> Per-source path size policies are specified by adding a ':' and the required policy to the corresponding mount point path, for example: snapm snapset create backup /:2G /var:1G /home </code></pre> snapm snapset create backup /:25%FREE /var:25%FREE /home </code></pre> snapm snapset create backup /:100%USED /var:100%USED /home </code></pre> snapm snapset create backup /:100%SIZE /var:100%SIZE /home </code></pre> If no size policy is specified the default is 200%USED</code> for mounted file systems and 25%SIZE for unmounted block devices. To ensure a volume can be completely overwritten specify 100%SIZE</code>. This requires more storage capacity but avoids the possibility of the snapshot running out of space. A default size policy for all source paths that do not specify an explicit per-path policy can be set with the --size-policy</code> argument: snapm snapset create backup --size-policy 100%SIZE / /home /var </code></pre> On success the snapm snapset create</code> command displays the newly created snapshot set on stdout: snapm snapset create -br --size-policy 100%USED backup / /home /var SnapsetName: backup Sources: /, /home, /var NrSnapshots: 3 Time: 2024-12-05 19:10:44 UUID: d3f5e3cd-a383-5dba-b597-9134a2c426e9 Status: Active Autoactivate: yes Bootable: yes BootEntries: SnapshotEntry: f574a20 RevertEntry: f428f9f </code></pre> Autoindex for recurring snapshot sets</h4> The --autoindex</code> argument allows creating a recurring snapshot set with a common basename and unique index (a non-negative integer). This can be used to take regular snapshots with a common name: snapm snapset create hourly --autoindex /:25%SIZE /var:25%SIZE SnapsetName: hourly.3 Sources: /, /var NrSnapshots: 2 Time: 2025-03-26 14:17:18 UUID: ae082452-7995-5316-ac65-388eadd9879c Status: Active Autoactivate: yes Bootable: no </code></pre> The basename and index values are available via the snapset list</code> report: snapm snapset list -o+basename,index SnapsetName Time NrSnapshots Status Sources Basename Index backup 2025-03-25 18:12:54 2 Invalid /, /var backup - hourly.0 2025-03-25 19:40:39 2 Invalid /, /var hourly 0 hourly.1 2025-03-26 14:17:11 2 Active /, /var hourly 1 hourly.2 2025-03-26 14:17:15 2 Active /, /var hourly 2 hourly.3 2025-03-26 14:17:18 2 Active /, /var hourly 3 </code></pre> snapset delete Delete an existing snapset by name or uuid. snapm snapset delete <name|uuid> </code></pre> snapset diff Compare two snapshot sets, or a snapshot set and the running system. snapm snapset diff [options] <from> <to> </code></pre> The from</code> and to</code> arguments specify the snapshot sets to compare. The special value .</code> may be used to refer to the running system (the root file system). The command detects added, removed, and modified files. File content comparisons can be performed to generate standard unified diffs. Supported output formats (-o</code>/--output-format</code>) include: paths - A simple list of changed paths</li> full - Detailed change information</li> short - Abbreviated change summary</li> json - JSON formatted change data</li> diff - Standard unified diff of file content</li> summary - Brief summary of the count of different change types</li> tree - A hierarchical tree view of changes (default)</li> </ul> The -o</code>/--output-format</code> option may be given multiple times to request different output formats for the same run. The diff</code> and summary</code> formats also accept an optional --stat</code> option to enable diffstat</code> style change summaries. The json</code> output format supports --pretty</code> to enable pretty-printing the JSON output. Compare the snapshot set "backup" to the running system using a tree view: snapm snapset diff --output-format tree backup . </code></pre> Generate a unified diff of content changes between two snapshot sets, ignoring file modification times to focus only on content: snapm snapset diff --output-format diff --ignore-timestamps weekly.0 weekly.1 </code></pre> Options are available to control the comparison: --content-only</code> / -c</code>: Only check for file content changes</li> --ignore-timestamps</code> / -t</code>: Ignore modification times</li> --ignore-permissions</code> / -p</code>: Ignore permission changes</li> --ignore-ownership</code> / -w</code>: Ignore ownership changes</li> --include-pattern</code> / --exclude-pattern</code>: Filter paths using glob patterns</li> </ul> Output Formats</h4> The --output-format</code> argument controls the presentation of differences. Available formats are: paths: Lists modified paths, one per line. Useful for piping to other tools or scripts. </li> </li> </ul> full: Provides a detailed report including old and new file attributes (permissions, ownership, size, modification time) for every change. </li> </ul> short: A concise summary listing the change status code and path for each modified file. </li> </ul> json: Outputs the complete difference data as a JSON object, suitable for parsing by external tools and automation scripts. </li> </ul> diff: Generates a standard unified diff of content changes for modified files. This format is useful for generating patches or detailed content review. </li> </ul> summary: Brief summary of the count of different change types. Change types are colorized using the same coding as tree</code> output. </li> </ul> tree: (Default) Displays changes in a hierarchical tree structure, similar to the standard tree</code> command but annotated with change status. The default if no --output-format</code> option is given is tree</code>. Tree Output Legend</h4> The tree output format uses specific prefixes and colors (if enabled) to indicate the type of change: </li> </ul> [+]</code> Path added (green): The file or directory is present in the target but not the source. </li> </ul> [-]</code> Path removed (red): The file or directory is present in the source but not the target. </li> </ul> []</code> Path modified (yellow): The file content or attributes have changed. </li> </ul> [<]</code> Path moved from (cyan): The source path of a renamed or moved file. </li> </ul> [>]</code> Path moved to (cyan): The destination path of a renamed or moved file. </li> </ul> [!]</code> Path file type changed (blue): The file type (regular file, symlink, directory, etc.) has changed between source and target. snapset diffreport Generate a tabular report of differences between snapshot sets. snapm snapset diffreport [options] <from> <to> </code></pre> This command performs the same comparison logic as snapset diff</code> but formats the output as a column-based report. It accepts standard reporting arguments including --options</code>, --sort</code>, --noheadings</code>, and --json</code>. snapm snapset diffreport --json backup current </code></pre> To list specific fields describing the changes: snapm snapset diffreport -opath,state,size_diff old_snap new_snap </code></pre> snapset rename Rename an existing snapset. snapm snapset rename <old_name> <new_name> </code></pre> snapset revert 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. snapm snapset revert <name|uuid> </code></pre> If the origins of the snapshot set are in use at the time of the revert the operation is deferred until the next time the snapshot set is activated (for example during a reboot). If a revert boot entry was created for the snapshot set the revert</code> command will suggest booting into it to continue: snapm snapset revert upgrade WARNING - Snapshot set upgrade origin is in use: reboot required to complete revert Boot into 'Revert upgrade 2024-06-10 15:25:15 (6.8.9-300.fc40.x86_64)' to continue </code></pre> snapset resize Resize the members in an existing snapset, applying a new size policy to specified sources or applying a new default size policy to all snapshots within a snapset. Resize the /var</code> member of the snapshot set named upgrade to 100%SIZE: snapm snapset resize upgrade /var:100%SIZE </code></pre> Resize each member of the snapshot set named backup to the 200%USED size policy: snapm snapset resize backup --size-policy 200%USED </code></pre> snapset split 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. To split the source "/home" from the existing snapshot set "upgrade" into a new snapshot set named "noupgrade": snapm snapset split upgrade noupgrade /home SnapsetName: noupgrade Sources: /home NrSnapshots: 1 Time: 2025-03-31 20:21:29 UUID: 30e69b86-5c48-5e5d-be1a-bf3d63aef8f7 Status: Inactive Autoactivate: no Bootable: no </code></pre> snapset activate Activate the members of an existing snapset, or all snapsets if no name or uuid argument is given. snapm snapset activate [<name|uuid>] </code></pre> snapset deactivate Deactivate the members of an existing snapset, or all snapsets if no name or uuid argument is given. snapm snapset deactivate [<name|uuid>] </code></pre> snapset autoactivate Enable or disable autoactivation for the snapshots in a snapshot set. snapm snapset autoactivate [--yes|--no] [<name|uuid>] </code></pre> snapset list List available snapsets matching selection criteria. snapm snapset list [<name|uuid>] </code></pre> By default the information is presented as a tabular report with column headings indicating the meaning of each value. The default column selection includes the SnapsetName, Time, NrSnapshots, Status, and Sources fields: snapm snapset list SnapsetName Time NrSnapshots Status Sources backup 2024-12-05 19:14:03 3 Active /, /home, /var upgrade 2024-12-05 19:14:09 2 Active /, /var </code></pre> Custom field specifications may be given with the -o</code>/--options</code> argument. To obtain a list of available fields run snapm snapset list -ohelp</code>: snapm snapset list -ohelp 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] </code></pre> To specify custom fields pass a comma separated list to -o</code>: snapm snapset list -oname,time SnapsetName Time backup 2024-12-05 19:14:03 upgrade 2024-12-05 19:14:09 </code></pre> To add fields to the default field set prefix the list of fields with the +</code> character: snapm snapset list -o+bootentry,revertentry SnapsetName Time NrSnapshots Status Sources SnapshotEntry RevertEntry backup 2024-12-05 19:14:03 3 Active /, /home, /var 41573a414f9d5 1cc5bc59c9b90 upgrade 2024-12-05 19:14:09 2 Active /, /var a60dab4d3fb36 4ce6b27f16f30 </code></pre> The report can also be produced in JSON notation, suitable for parsing by other tools using the --json</code> argument: snapm snapset list --json { "Snapsets": [ { "snapset_name": "backup", "snapset_time": "2024-12-05 19:14:03", "snapset_nr_snapshots": 3, "snapset_status": "Active", "snapset_sources": [ "/", "/home", "/var" ] }, { "snapset_name": "upgrade", "snapset_time": "2024-12-05 19:14:09", "snapset_nr_snapshots": 2, "snapset_status": "Active", "snapset_sources": [ "/", "/var" ] } ] } </code></pre> JSON reports use the full report field name (including the snapset_</code>, snapshot_</code>, schedule_</code>, or plugin_</code> prefix). Fields and sort order are specified with --options</code> and --sort</code> as usual. For further report formatting options refer to the snapm(8)</code> manual page. snapset show Display available snapsets matching selection criteria. snapm snapset show [<name|uuid>] </code></pre> By default the output is formatted in the same way as the output of the snapm snapset create</code> command: snapm snapset show upgrade SnapsetName: upgrade Sources: /, /var NrSnapshots: 2 Time: 2024-12-05 19:14:09 UUID: 87c6df8f-bd8c-5c9d-b081-4f6d6068cc07 Status: Active Autoactivate: yes Bootable: yes BootEntries: SnapshotEntry: a60dab4 RevertEntry: 4ce6b27 </code></pre> The individual snapshots making up each set are also displayed if --members</code> is used: snapm snapset show --members SnapsetName: upgrade Sources: /, /var NrSnapshots: 2 Time: 2024-12-05 19:19:30 UUID: f0a46cde-9eed-5335-b239-66ed53e5b503 Status: Active Autoactivate: yes Bootable: yes BootEntries: SnapshotEntry: dfce8d8 RevertEntry: fc414b0 Snapshots: Name: fedora/root-snapset_upgrade_1733426370_- SnapsetName: upgrade Origin: /dev/fedora/root Time: 2024-12-05 19:19:30 Source: / MountPoint: / Provider: lvm2-cow UUID: 7566dde3-96f4-5288-8b15-18be7c520327 Status: Active Size: 8.8GiB Free: 8.8GiB Autoactivate: yes DevicePath: /dev/fedora/root-snapset_upgrade_1733426370_- VolumeGroup: fedora LogicalVolume: root-snapset_upgrade_1733426370_- Name: fedora/var-snapset_upgrade_1733426370_-var SnapsetName: upgrade Origin: /dev/fedora/var Time: 2024-12-05 19:19:30 Source: /var MountPoint: /var Provider: lvm2-cow UUID: 22674f3e-f5c4-5632-9add-2df51985679e Status: Active Size: 6.4GiB Free: 6.4GiB Autoactivate: yes DevicePath: /dev/fedora/var-snapset_upgrade_1733426370_-var VolumeGroup: fedora LogicalVolume: var-snapset_upgrade_1733426370_-var </code></pre> The output is also available in JSON notation using the --json</code> argument: snapm snapset show --json before-upgrade [ { "SnapsetName": "before-upgrade", "Sources": [ "/", "/var" ], "MountPoints": [ "/", "/var" ], "Devices": [], "NrSnapshots": 2, "Timestamp": 1756555124, "Time": "2025-08-30 12:58:44", "UUID": "87e31113-75a5-5eb6-b016-762639a2c7ed", "Status": "Active", "Autoactivate": true, "Bootable": true, "BootEntries": { "SnapshotEntry": "7c56dc0", "RevertEntry": "457f733" } } ] </code></pre> The show --json</code> command uses the normal show</code> output property names as the JSON keys. A BootEntries</code> object will be added if either boot or revert entries are configured for the snapshot set. Snapshot Commands</h2> The snapshot</code> command is used to manipulate, list, and display snapshots. snapshot activate Activate individual snapshots matching selection criteria. snapm snapshot activate [-N name] [-U uuid] [<name|uuid>] </code></pre> snapshot deactivate Deactivate individual snapshots matching selection criteria. snapm snapshot deactivate [-N name] [-U uuid] [<name|uuid>] </code></pre> snapshot autoactivate Enable or disable autoactivation for individual snapshots matching selection criteria. snapm snapshot autoactivate [--yes|--no] [-N name] [-U uuid] [<name|uuid>] </code></pre> snapshot list List available snapshots matching selection criteria. snapm snapshot list [<name|uuid>] </code></pre> By default the information is presented as a tabular report with column headings indicating the meaning of each value. The default column selection includes the SnapsetName, Name, Origin, Source, Status, Size, Free, Autoactivate, and Provider fields: snapm snapshot list SnapsetName Name Origin Source Status Size Free Autoactivate Provider upgrade fedora/root-snapset_upgrade_1733426499_- /dev/fedora/root / Active 8.8GiB 8.8GiB yes lvm2-cow upgrade fedora/var-snapset_upgrade_1733426499_-var /dev/fedora/var /var Active 6.4GiB 6.4GiB yes lvm2-cow upgrade fedora/home-snapset_upgrade_1733426499_-home /dev/fedora/home /home Active 1.0GiB 1.9GiB yes lvm2-thin </code></pre> Note: For thin‑provisioned snapshots (lvm2‑thin, Stratis), “Free” reflects thin‑pool free space and may exceed “Size”. </blockquote> snapshot show Display available snapshots matching selection criteria. snapm snapshot show [<name|uuid>] </code></pre> Plugin Commands</h2> The plugin</code> command is used to display information on the available snapshot provider plugins. plugin list The plugin list</code> command lists the available plugins: snapm plugin list PluginName PluginVersion PluginType lvm2-cow 0.1.0 Lvm2CowSnapshot lvm2-thin 0.1.0 Lvm2ThinSnapshot stratis 0.1.0 StratisSnapshot </code></pre> Schedule Commands</h2> The schedule</code> command is used to create, display and manage schedules for automatic snapshot set creation. schedule create Create a new schedule with the provided name and list of sources (mount point or block device paths): snapm schedule create [-b|--bootable] [-r|--revert] [--size-policy policy] [-p|--policy-type policy_type] [--keep-count count] [--keep-years years] [--keep-months months] [--keep-weeks weeks] [--keep-days days] [--keep-yearly yearly] [--keep-quarterly quarterly] [--keep-monthly monthly] [--keep-weekly weekly] [--keep-daily daily] [--keep-hourly hourly] --calendarspec calendarspec <name> source... </code></pre> snapm schedule create --policy-type count --keep-count 2 --bootable --revert --size-policy 25%SIZE --calendarspec hourly hourly / /var Name: hourly SourceSpecs: /, /var DefaultSizePolicy: 25%SIZE Calendarspec: hourly Boot: yes Revert: yes GcPolicy: Name: hourly Type: Count Params: keep_count=2 Enabled: yes Running: yes </code></pre> schedule delete</h3> Delete an existing schedule by name: snapm schedule delete <name> </code></pre> schedule edit</h3> Modify an existing schedule by name: snapm schedule edit [-b|--bootable] [-r|--revert] [--size-policy policy] [-p|--policy-type policy_type] [--keep-count count] [--keep-years years] [--keep-months months] [--keep-weeks weeks] [--keep-days days] [--keep-yearly yearly] [--keep-quarterly quarterly] [--keep-monthly monthly] [--keep-weekly weekly] [--keep-daily daily] [--keep-hourly hourly] --calendarspec calendarspec <name> [source...] </code></pre> schedule enable Enable an existing schedule by name: snapm schedule enable <name> </code></pre> schedule disable</h3> Disable an existing schedule by name: snapm schedule disable <name> </code></pre> schedule list</h3> List configured schedules: snapm schedule list [--nameprefixes] [--noheadings] [--options fields] [--sort fields] [--rows|--json] [--separator separator] </code></pre> snapm schedule list ScheduleName ScheduleSources SizePolicy OnCalendar Enabled custom /, /home:100%SIZE, /var 50%SIZE -*-1 01:00:00 yes monthly /:25%SIZE, /var:25%SIZE monthly no hourly /, /var 25%SIZE hourly yes </code></pre> schedule show</h3> Display configured schedule: snapm schedule show <name> </code></pre> schedule gc</h3> Run configured garbage collection policy for schedule: snapm schedule gc <name> </code></pre> Reporting Commands</h2> The snapm snapset list</code>, snapm snapshot list</code>, snapm plugin list</code>, and snapm schedule list</code> commands generate a tabular report as output. To control the list of displayed fields use the -o</code>/--options FIELDS</code> argument: snapm snapset list -oname,sources SnapsetName Sources backup /, /home, /var userdata /data, /home </code></pre> To add extra fields to the default selection, prefix the field list with the +</code> character: snapm snapset list -o+uuid SnapsetName Time NrSnapshots Status Sources UUID backup 2024-12-05 19:26:28 3 Active /, /home, /var 53514020-e88d-5f53-bf09-42c6ab6e325d userdata 2024-12-05 19:26:45 2 Inactive /data, /home e8d58051-7a94-5802-8328-54661ab1a70f </code></pre> To display the available fields for either report use the field name help</code>: snapm snapset list -ohelp Snapshot set Fields ------------------- name - Snapshot set name [str] uuid - Snapshot set UUID [uuid] basename - Snapshot set basename [str] index - Snapshot set index [idx] 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] </code></pre> JSON Output</h3> All reports can optionally be formatted as JSON for parsing by other tools using the --json</code> argument: snapm snapset list --json { "Snapsets": [ { "snapset_name": "backup", "snapset_time": "2025-09-09 17:12:21", "snapset_nr_snapshots": 3, "snapset_status": "Inactive", "snapset_sources": [ "/", "/home", "/var" ] }, { "snapset_name": "before-upgrade", "snapset_time": "2025-09-08 18:43:57", "snapset_nr_snapshots": 2, "snapset_status": "Active", "snapset_sources": [ "/", "/var" ] } ] } </code></pre> The create</code> and show</code> commands also support optional JSON output using the --json</code> argument. In this case the JSON schema maps the normal show</code> output property names to JSON keys: snapm snapset show --json before-upgrade [ { "SnapsetName": "before-upgrade", "Sources": [ "/", "/var" ], "MountPoints": [ "/", "/var" ], "Devices": [], "NrSnapshots": 2, "Timestamp": 1757353437, "Time": "2025-09-08 18:43:57", "UUID": "6330328b-a9d0-5b41-ac96-53b371449965", "Status": "Active", "Autoactivate": true, "Bootable": true, "BootEntries": { "SnapshotEntry": "66dc7ad", "RevertEntry": "6832c11" } } ] </code></pre> Common Use Cases</h2> System Updates and Rollback</h3> Before performing system updates, create a bootable snapshot: Create snapshot set before update: snapm snapset create --bootable --revert pre-update / /var </code></pre> Perform system update: dnf update </code></pre> If update causes issues, revert: snapm snapset revert pre-update </code></pre> Or boot into snapshot from boot menu (select: "Snapshot pre-update YYYY-MM-DD HH:MM:SS (version)"): reboot </code></pre> Clean up when satisfied with update: snapm snapset delete pre-update </code></pre> Development and Testing</h3> Create development checkpoints for experimental work: Create checkpoint before major changes:</li> </ul> snapm snapset create dev-checkpoint /home /var/lib/myapp </code></pre> Make experimental changes</li> If changes don't work out, revert:</li> </ul> snapm snapset revert dev-checkpoint </code></pre> Data Protection</h3> Regular data snapshots for important directories allow backups to be captured from snapshots, lowering production impact by reducing backup downtime. Daily backup of user data: snapm snapset create daily-backup /home /var/lib/database </code></pre> Weekly system snapshots: snapm snapset create weekly-system / /var --size-policy 50%SIZE </code></pre> Automated Scheduling</h3> Set up automated snapshot schedules: Hourly snapshots, keep 24: snapm schedule create --autoindex \ --policy-type count \ --keep-count 24 \ --calendarspec hourly \ hourly / /home </code></pre> Daily snapshots, keep 7 days: snapm schedule create --autoindex \ --policy-type age \ --keep-days 7 \ --calendarspec daily \ daily / /home /var </code></pre> Monthly bootable snapshots, keep 12: snapm schedule create --autoindex \ --bootable --revert \ --policy-type timeline \ --keep-monthly 12 \ --calendarspec monthly \ monthly / /var </code></pre> Configuration Management</h3> Snapshot configuration changes: Before modifying system configuration: snapm snapset create config-backup /etc /var/lib/config </code></pre> Make configuration changes: vim /etc/myapp/config.conf </code></pre> Test changes... If configuration breaks system, revert: snapm snapset revert config-backup </code></pre> Best Practices</h2> Naming Conventions</h3> Use consistent, descriptive naming: Good examples: pre-kernel-update-6.5.0-snap</li> before-database-migration</li> dev-checkpoint-feature-x</li> </ul> Avoid generic names: backup</li> test</li> snapshot1</li> </ul> Size Policy Guidelines</h3> For system volumes (/</code>, /var</code>): Use 100%SIZE</code> for critical systems, 200%USED</code> for normal use</li> For data volumes (/home</code>): Use 100%USED</code> or 50%SIZE</code> depending on change frequency</li> For database volumes: Use 300%USED</code> or 100%SIZE</code> for heavy write workloads</li> </ul> Retention Policies</h3> Plan retention based on your needs: Hourly: Keep 6-12 snapshots for short-term recovery</li> </li> </ul> Daily: Keep 3-7 snapshots for medium-term recovery Weekly: Keep 2-4 snapshots for long-term recovery</li> Monthly: Keep 3-6 snapshots for archival purposes</li> </ul> Monitoring and Maintenance</h3> Regular maintenance tasks: Check snapshot space usage: snapm snapshot list -o name,size,free </code></pre> Clean up old snapshots: snapm snapset delete old-snapshot-name </code></pre> Review scheduled snapshots: snapm schedule list </code></pre> Access Control</h3> Snapm requires root privileges for most operations. Consider: Using sudo with specific command restrictions</li> Creating wrapper scripts for common operations</li> Implementing audit logging for snapshot operations</li> </ul> Data Sensitivity</h3> Remember that snapshots contain complete copies of data: Consider encryption for sensitive data</li> Implement proper cleanup procedures for temporary snapshots</li> </ul> Boot Security</h3> Bootable snapshots can bypass some security measures: Bootable snapshot sets use the kernel present at the time of snapshot creation: older kernels may contain security vulnerabilities patched in newer builds. </li> Consider password protecting GRUB and enforcing physical access controls. </li> </ul> Integration Examples With Systemd Services</h3> Create consistent snapshots by ensuring services are in a stable state: Stop service before snapshot: systemctl stop myapp snapm snapset create myapp-maintenance /var/lib/myapp systemctl start myapp </code></pre> Alternatively isolate to rescue mode for system-wide consistency: systemctl isolate rescue.target snapm snapset create system-maintenance / /var systemctl isolate multi-user.target </code></pre> With Backup Systems</h3> Integrate with existing backup workflows: Create consistent snapshot for backup: snapm snapset create backup /home /var/lib/data </code></pre> Mount individual snapshots for backup tools: mkdir -p /mnt/snapshot-backup/home mount /dev/fedora/home-snapset_backup_1757533502_-home /mnt/snapshot-backup/home ... </code></pre> Run backup tools against mounted snapshot: rsync -av /mnt/snapshot-backup/home backup-server:/backups/ ... </code></pre> Clean up: umount /mnt/snapshot-backup/home snapm snapset delete backup </code></pre> With Configuration Management</h3> Use with Ansible, Puppet, etc.: Pre-deployment snapshot: snapm snapset create pre-deploy-$(date +%Y%m%d) /etc /var/www </code></pre> Run deployment: ansible-playbook deploy.yml </code></pre> Verify deployment: curl -f http://localhost/health || { echo "Deployment failed, reverting..." snapm snapset revert pre-deploy-$(date +%Y%m%d) } </code></pre> Troubleshooting</h2> Common Issues</h3> Snapshot creation fails with "No space left" Check available space and adjust size policies: Check current usage: vgs stratis pool list </code></pre> Use smaller size policy: snapm snapset create backup --size-policy 50%USED / </code></pre> Boot entries not appearing Ensure boom is properly installed and configured: Check boom installation: rpm -q boom-boot boom list </code></pre> Verify boom configuration: boom profile list </code></pre> Snapshot activation fails Check snapshot status and storage health: Check snapshot status: snapm snapshot list </code></pre> Check LVM and Stratis status: lvs vgs stratis pool list </code></pre> Check for storage errors: journalctl --priority err dmesg | grep -i err </code></pre> Snapshot space exhaustion When snapshots are close to running out of space: Check snapshot usage: snapm snapshot list -o name,size,free </code></pre> Resize snapshot if possible: snapm snapset resize my-snapset /var:500%USED </code></pre> If necessary resize the LVM2 volume group, thin pool, or Stratis pool to create more space for snapshot storage. Permission denied errors Ensure snapm is run as the root user: snapm snapset create before-upgrade / /var $ sudo snapm snapset create before-upgrade / /var </code></pre> LVM thin pool issues For thin provisioning problems: Check thin pool status: sudo lvs -a -o +data_percent,metadata_percent </code></pre> Extend thin pool if needed: sudo lvextend -L+1G /dev/vg/thin_pool </code></pre> Check thin pool metadata: sudo thin_check /dev/vg/thin_pool_tmeta </code></pre> Stratis backend issues For Stratis-related problems: Check Stratis daemon status: systemctl status stratisd </code></pre> List Stratis pools and filesystems: stratis pool list stratis filesystem list </code></pre> Check Stratis logs: journalctl -u stratisd </code></pre> Performance Considerations</h3> Snapshot Size Planning Use 100%SIZE</code> for complete protection but higher space usage</li> Use 200%USED</code> for balance between protection and space efficiency</li> Use 50%USED</code> or 25%SIZE</code> for space-constrained environments</li> </ul> Storage Performance LVM2 thin provisioning generally offers better performance than copy-on-write</li> Consider separate storage for snapshot backstores in high-I/O environments</li> Monitor snapshot space usage to prevent exhaustion</li> </ul> Debugging</h2> Debug Mode</h3> Enable debug mode with very verbose output: snapm -d all -vv snapset create debug-test /home </code></pre> Enable specific debug categories with very verbose output: snapm -vv -d command,plugin snapset list </code></pre> Basic verbose output: snapm -v snapset show my-snapset </code></pre> Log Analysis</h3> Check system logs for snapm timer unit activity: Check snapm logs: journalctl --boot 0 | grep -- snapm- </code></pre> Check for storage-related messages: journalctl --boot 0 | grep -i lvm dmesg | grep 'Buffer I\/O error' </code></pre> Check for filesystem errors: journalctl --boot 0 | grep -i ext4 journalctl --boot 0 | grep -i xfs </code></pre> Storage Backend Debugging</h3> Debugging Provider/Plugin Problems When snapshot operations fail, check provider-specific status: Check available plugins: snapm plugin list </code></pre> For LVM2 issues, check LVM status: lvs -a vgs pvs </code></pre> For Stratis issues, check daemon and pools: systemctl status stratisd stratis pool list stratis filesystem list </code></pre> Configuration Validation</h3> Verify snapm configuration: snapm -vv --debug=all plugin list </code></pre> Validate boom integration: boom list boom profile list </code></pre> Getting Help</h2> Command Line Help</h3> Help is available for the snapm</code> command and each subcommand: General help: snapm --help </code></pre> Command type help: snapm snapset --help snapm snapshot --help snapm schedule --help snapm plugin --help </code></pre> Specific command help: snapm snapset create --help snapm snapset list --help </code></pre> Manual Pages</h3> Full command, option, argument, and configuration documentation is available in the manual pages: man 8 snapm man 5 snapm.conf man 5 snapm-plugins.d man 5 snapm-schedule.d </code></pre> Field Reference</h3> Get available fields for reports: Snapset fields: snapm snapset list -ohelp </code></pre> Snapshot fields: snapm snapshot list -ohelp </code></pre> Schedule fields: snapm schedule list -ohelp </code></pre> Plugin fields: snapm plugin list -ohelp </code></pre> Version Information</h3> Check snapm version and component information: Show version: snapm --version </code></pre> Show plugin versions: snapm plugin list </code></pre> Online Resources</h3> Additional help and documentation: Project Homepage: https://github.com/snapshotmanager/snapm</a></li> Documentation: https://snapm.readthedocs.io/</a></li> Issue Tracker: https://github.com/snapshotmanager/snapm/issues</a></li> Wiki: https://github.com/snapshotmanager/snapm/wiki</a></li> Mailing List: snapm-users@lists.fedoraproject.org</li> </ul> Community Support</h3> Get help from the community: GitHub Issues: https://github.com/snapshotmanager/snapm/issues</a></li> </ul> Filing Bug Reports When reporting issues, include: Snapm version (snapm --version</code>) </li> Operating system and version </li> Storage backend information </li> Complete error messages </li> Debug output (snapm -vv --debug=all <command></code>) </li> Steps to reproduce the issue </li> </ul> Example bug report template: Snapm Version: 0.4.3 OS: Fedora 42 x86_64 Storage: LVM2 with thin provisioning Error: Snapshot creation fails with permission denied Steps to reproduce: 1. sudo snapm snapset create test /home 2. Error appears immediately Debug output: snapm -vv -d all snapset create test /home [debug output here] Additional context: - Works with root user - Sudo configuration appears correct </code></pre> Appendix</h2> Storage Backend Details</h3> LVM2 Copy-on-Write Requires fixed size allocation </li> Good for infrequent snapshots </li> Lower performance impact during normal operation </li> Higher space requirements </li> </ul> LVM2 Thin Provisioning Dynamic space allocation</li> Better space efficiency</li> Good performance characteristics</li> Requires thin pool configuration</li> </ul> Stratis Modern storage management</li> Automatic thin provisioning</li> Integrated with systemd</li> Requires Stratis daemon</li> </ul> Exit Codes</h3> Snapm commands return standard exit codes: 0: Success</li> 1: Runtime error</li> 2: Invalid arguments / parse error</li> </ul>

5.3 PyPi Packages</h3>
The PyPi (pip) packages include only the executable code that makes up Snapshot Manager. You will need to configure the program yourself and install any documentation you wish to use, following the directions in section 3.</a>.</p>

Overview</h1>
This is a maintenance release for snapm-0.5-stable</a> that includes two bug fixes.</p>
Users of snapm-0.5.x who are unable to upgrade to a later y-stream release should update to v0.5.3</a> as soon as possible to take advantage of these fixes.</p>

What's Changed</h2>

Timeline index fix for v0.5.2 by @bmr-cymru</a> in #609</a></li>
boot: hex escape literal ':' in values passed to systemd.{mount,swap}-extra by @bmr-cymru</a> in #894</a></li> </ul>
Full Changelog</strong>: v0.5.2..v0.5.3</a></p>

Known issues</h2>
There is one known issue for this release. Please see the wiki pages for more details, status, and workarounds:</p>

snapm snapset {mount,umount} and podman netfs mounts</a></li> </ul>
This will be addressed in a future release.</p>
Full Changelog</strong>: v0.5.2...v0.6.0</a></p>

Common Use Cases</h2>

Best Practices</h2>

Troubleshooting</h2>

Debugging</h2>

Getting Help</h2>

Appendix</h2>

Exit Codes</h3>
Snapm commands return standard exit codes:</p>

0</strong>: Success</li>
1</strong>: Runtime error</li>
2</strong>: Invalid arguments / parse error</li> </ul>

Snapshot Manager

Frequently Asked Questions (FAQs)

Frequently Asked Questions (FAQs)</h1>
Our users ask a lot of reasonable and insightful questions about `snapm</code> and its usage. We have collected together some of the more common ones in this post, along with their corresponding answers.</p>`

Your First Snapshot Set

Getting snapm

snapm 0.7.0 Release Notes

snapm 0.5.3 Release Notes

snapm 0.6.0 Release Notes

Snapshot Manager how-to/walkthrough

Welcome!

Welcome!</h1>
Welcome to the Snapshot Manager</em> blog! We'll be sharing news, release announcements, future plans and updates, technical tips and more.</p>
Come back soon or subscribe to our feed to be notified of updates.</p>

Stratis Clients and Supported Operating Systems

Snapshot Manager

Frequently Asked Questions (FAQs)

Frequently Asked Questions (FAQs)</h1> Our users ask a lot of reasonable and insightful questions about snapm</code> and its usage. We have collected together some of the more common ones in this post, along with their corresponding answers.</p>

Your First Snapshot Set

Getting snapm

2. Installing copr builds from GitHub (early access to new features & fixes)</h2> What you'll need:</p> The URL or PR# of the pull request that you want to install a build from.</p> </li>

snapm 0.7.0 Release Notes

snapm 0.5.3 Release Notes

snapm 0.6.0 Release Notes

Notes</h2> It is now possible to mount individual snapshot sets and interact with them using the snapset {mount,umount}</code>, snapset exec</code>, and snapset shell</code> commands. Snapshot sets are mounted under /run/snapm/mounts</code>.</li>

Known issues</h2> There is one known issue for this release. Please see the wiki pages for more details, status, and workarounds:</p>

Snapshot Manager how-to/walkthrough

Common Use Cases</h2>

Best Practices</h2>

Troubleshooting</h2>

Debugging</h2>

Getting Help</h2>

Community Support</h3> Get help from the community:</p>

Appendix</h2>

Exit Codes</h3> Snapm commands return standard exit codes:</p> 0</strong>: Success</li> 1</strong>: Runtime error</li> 2</strong>: Invalid arguments / parse error</li> </ul>

Welcome!

Welcome!</h1> Welcome to the Snapshot Manager</em> blog! We'll be sharing news, release announcements, future plans and updates, technical tips and more.</p> Come back soon or subscribe to our feed to be notified of updates.</p>

Stratis Clients and Supported Operating Systems

Frequently Asked Questions (FAQs)</h1>
Our users ask a lot of reasonable and insightful questions about `snapm</code> and its usage. We have collected together some of the more common ones in this post, along with their corresponding answers.</p>`

Known issues</h2>
There is one known issue for this release. Please see the wiki pages for more details, status, and workarounds:</p>

snapm snapset {mount,umount} and podman netfs mounts</a></li> </ul>
This will be addressed in a future release.</p>
Full Changelog</strong>: v0.5.2...v0.6.0</a></p>

Exit Codes</h3>
Snapm commands return standard exit codes:</p>

0</strong>: Success</li>
1</strong>: Runtime error</li>
2</strong>: Invalid arguments / parse error</li> </ul>

Welcome!</h1>
Welcome to the Snapshot Manager</em> blog! We'll be sharing news, release announcements, future plans and updates, technical tips and more.</p>
Come back soon or subscribe to our feed to be notified of updates.</p>