openSUSE:Snapper Tutorial
Introduction
Snapper is a tool for filesystem snapshot management.
This article assumes you will be using Snapper with the Btrfs filesystem.
During a fresh install of openSUSE, the default is to use Btrfs on root, meaning / and the filesystem XFS on /home. If you select the option to not seperate /home during openSUSE install, the default is for everything, including /home, to be under Btrfs.
If you decide to use Btrfs & Snapper (default) during a fresh openSUSE install, it will automatically configure Snapper for you. This automatic configuration of Snapper means that snapshots will be taken automatically when you use YaST2 and/or Zypper. Please read section Software Requirements below for caveat.
You may convert EXT3 & EXT4 filesystems to Btrfs to take advantage of Snapper. Using Snapper on EXT4 filesystem is highly discouraged.
Important Details
The default behavior when Snapper is configured to run on root, meaning /, is to exclude every Btrfs subvolume. This is the same behavior as on SUSE Enterprise. This means that if you have the subvolume /srv Snapper will not take snapshots of anything in /srv unless told specifically by you to do so. This also means that if you add a subvolume to / at any point in time, it will be excluded from Snapper's default snapshot behavior.
Always be root when using Snapper or YaST2, unless otherwise specified.
YaST2 comes with a Snapper module called yast2-snapper and may be used to check and manipulate snapshots. It does not, however, have the ability to change Snapper configurations. That must be done in the terminal.
Taking snapshots is automatically enabled if the root partition (/) is big enough (approximately more than 16 GB).
WARNING: Please remember if the disk is smaller than 16 GB, all Snapper features and automatic snapshots are disabled to prevent a full / partition. Disabled features include the automatic configuration of the / partition.
See https://bugzilla.opensuse.org/show_bug.cgi?id=1085378 for details.
Snapper Default Aspects for Disks > 16 GB and < 16 GB
- Disk > 16 GB (See https://doc.opensuse.org/documentation/leap/reference/html/book-opensuse-reference/cha-snapper.html#sec-snapper-setup)
- Disk < 16 GB (e.g. VirtualBox VDI fix-sized disk is 8Gb by default, which is OK to have a test platform for (open-)SUSE before its deployment on real machine(-s).)
| Disk > 16 GB | Disk < 16 GB |
|---|---|
1. Config /etc/snapper/configs/root (0 single) is created automatically. |
1. No config /etc/snapper/configs/root (0 single) is created automatically. Should be created manually by Snapper's create-config / command).
|
2. Snapshot 1 single for root partition (/) is taken automatically with name 'first root filesystem' |
2. No snapshot 1 single is automatically taken. Reason: 1. User can create it manually with any name. |
| 3. Snapshot 2 single 'After installation', important=yes, is taken automatically. | 3. No single 2 snapshot is automatically created. Reason: 1. |
4. Default USE_SNAPPER=yes parameter in /etc/sysconfig/yast2 config. Administrative Snapshots creation is ON. |
4. Default USE_SNAPPER=no parameter in /etc/sysconfig/yast2 config. Administrative Snapshots creation is OFF.
|
5. Default TIMELINE_CREATE=yes in /etc/snapper/configs/root. This means, that Timeline Snapshots creation is ON. |
5. Default TIMELINE_CREATE=no in /etc/snapper/configs/root. Timeline Snapshots creation is OFF.
|
To see what subvolumes are created under / and therefore see which directories (subvolumes) are excluded from the default snapshots behaviour:
# btrfs subvolume list /
To have Snapper take a snapshot of a subvolume, you can either do it manually one-time via the snapper program, or create a new Snapper config file. More information in the tutorial.
Software Requirements
You always need this package:
snapper
If you use YaST2 to install, update or remove packages and want to have Snapper automatically take snapshots when you use this tool:
yast2-snapper
If you use Zypper to install, update or remove packages and want to have Snapper automatically take snapshots when you use this tool:
snapper-zypp-plugin
If you use DNF to install, update or remove packages and want to have Snapper automatically take snapshots when you use this tool:
python3-dnf-plugin-snapper
If you want to have the ability for advanced Btrfs snapshot boot menu management:
grub2-snapper-plugin
WARNING: the above packages are not always installed by default. What gets installed depends on what choices you make during the openSUSE installation process. Make sure you have the appropriate (usually that means all) packages listed above installed before making changes to your system, otherwise you may be in for a surprise when snapper does not automatically create snapshots you thought it would.
Snapper Basic Usage
Snapper is not restricted to creating and managing snapshots automatically by configuration; you can also create snapshot pairs ("before and after") or single snapshots manually using either the command line tool or the YaST module.
All Snapper operations are carried out for an existing configuration. You can only take snapshots of partitions or volumes for which a configuration exists. By default the system configuration (root) is used. If you want to create or manage snapshots for your own configuration you need to explicitly choose it. Use the Current Configuration drop-down box in YaST or specify the -c on the command line (snapper -c MYCONFIG COMMAND).
List all snapshots for the default configuration (root)
# snapper list
or
# snapper ls
Show which files and directories have been changed between snapshots
For files/directories changed between snapshot 21 and 22:
# snapper status 21..22
You can also show what files and directories have been changed from snapshot 41 going back to 39:
# snapper status 41..39
The output consists of a string encoding the status followed by the filename. The characters of the status string by column are:
- "+" means the file was created, or "-" means the file was deleted, or "c" means the content of the file has changed, or "t" means the type of the file has changed (e.g. from regular file to directory);
- "p" means the permissions are have changed;
- "u" means the user ownership has changed;
- "g" means the group ownership has changed;
- "x" means the extended attribute information has changed;
- "a" means the ACL information has changed;
- "." in any column means no change.
Show the diff (difference in actual files) between snapshots
For diff between snapshot 71 and 72:
# snapper diff 71..72
You can also use this command to show the difference between a specific file. For example to show the diff from snapshot 71 to 72 only for file /etc/zypp/zypp.conf you would do the following:
# snapper diff 71..72 /etc/zypp/zypp.conf
Cleanup Algorithms
Unless you have a good reason to do otherwise, you should always specify the cleanup algorithm when taking a snapshot, otherwise the snapshot will never be deleted unless you do it manually. You do this by adding the following to your snapper commands:
--cleanup-algorithm <number|timeline|empty-pre-post>
The following commands assume you will be taking snapshots using the default system configuration (root). As mentioned above, if you want to use the non-default configuration, add the following to the snapshot commands:
-c MYCONFIG
Takes a snapshot of the type pre and prints the snapshot number. First command needed to take a pair of snapshots used to save a "before" and "after" state.
# snapper create --type pre --print-number --description "Before the Apache config cleanup" --cleanup-algorithm number
Takes a snapshot of the type post paired with the pre snapshot number 30. Second command needed to take a pair of snapshots used to save a "before" and "after" state.
# snapper create --type post --pre-number 30 --description "After the Apache config cleanup" --cleanup-algorithm number
Takes a stand-alone snapshot (type single) for the default (root) configuration with a description. Because no cleanup-algorithm is specified, the snapshot will never be deleted automatically.
# snapper create --description "Snapshot for week 2 2022"
NOTE: For more details visit Leap's Reference Guide.
Automatic Snapshots Cleanup Mechanisms
To prevent disk space getting full, Snapper periodically cleans up snapshots. By default, this period = 1 day.
Automatic snapshots cleanup task can be managed via Systemd timer scheduler (snapper-cleanup.timer and snapper-cleanup.service Systemd units).
By default, Systemd timer mechanism is in use. The cron mechanism has been deprecated since Snapper version 0.5.3.
All cleanup mechanisms are based on status (boolean: yes/no) of these directives from particular partition config-file, stored in the /etc/snapper/configs/ directory:
- NUMBER_CLEANUP=boolean
- TIMELINE_CLEANUP=boolean
- EMPTY_PRE_POST_CLEANUP=boolean
NOTE: For more configuration options to modify the cleanup algorithms according to your needs visit Leap's Reference Guide and/or take a look at the snapper-configs(5) manpage:
man snapper-configs
Deleting Snapshots
To delete snapshot 65 for the default (root) configuration:
# snapper delete 65
If you want to instead delete all snapshots, first do snapper list as root user, then replace 100000 by the highest snapshot number, output by the previous snapper list command, in the following command:
# snapper delete 1-100000 (snapper delete number1-number2)
The currently mounted snapshot is automatically ignored in this process.
Snapper Tutorial
/ root and /home file systems. The default is to use Btrfs on / root, but not on /home. If your /home is not using Btrfs, this tutorial still applies, just do not follow through with the directions when it comes to configuring or using Snapper on /home.First let us check how YaST has configured Snapper:
# snapper list-configs Config | Subvolume -------+---------- root | /
As you can see YaST has created a snapper config called "root" for your root file system. You can see what snapshots exist:
# snapper list # | Type | Pre # | Date | User | Used Space | Cleanup | Description | Userdata ---+--------+-------+---------------------------------+------+------------+----------+-------------+--------- 0 | single | | | root | | | current | 1 | single | | Wed 19 Jan 2022 02:05:18 AM -03 | root | 31.41 MiB | timeline | timeline |
Snapshot #0 always refers to the current system. There might already be several other snapshots depending on the uptime of your system and on whether you already used YaST or Zypper.
Now we want to try Snapper as an undo tool for YaST. First we run YaST:
# yast2 system_settings
Within YaST enable the SysReq. After you have finished YaST you should see two new snapshots:
# snapper list # | Type | Pre # | Date | User | Used Space | Cleanup | Description | Userdata ---+--------+-------+---------------------------------+------+-------------+----------+----------------------+--------- 0 | single | | | root | | | current | 1 | single | | Wed 19 Jan 2022 02:05:18 AM -03 | root | 31.41 MiB | timeline | timeline | 2 | pre | | Wed 19 Jan 2022 02:15:03 AM -03 | root | 305.79 KiB | number | yast system_settings | 3 | post | 2 | Wed 19 Jan 2022 02:15:57 AM -03 | root | 520.01 KiB | number | |
Types of Snapshots
It's time to explain the types of snapshots. Snapper takes a snapshot before and after YaST runs, these snapshots are called pre and post respectively. The post snapshot knows which pre snapshot belongs to it. By having a pre and post snapshot we can see what changes happened to the filesystem while YaST was running. Single snapshots have no special relationship to other snapshots.
- Timeline Snapshots
- Installation Snapshots
- Administration Snapshots
NOTE: For more details visit Leap's Reference Guide.
Seeing What Has Changed (YaST)
Using snapper, it is easy to see what has changed while YaST was running. To do so you have to pass the number of the "pre" and "post" snapshot:
# snapper status 2..3 c..... /etc/sysctl.conf
The "c" means that the content of the file has changed.
We can also see the diff of the file:
# snapper diff 2..3 --- /.snapshots/2/snapshot/etc/sysctl.conf 2022-01-20 12:08:17.180364836 -0300 +++ /.snapshots/3/snapshot/etc/sysctl.conf 2022-01-20 13:06:37.149600689 -0300 @@ -17,7 +17,7 @@ # See sysctl.conf(5) and sysctl(8) for more information # #### -kernel.sysrq = 0 +kernel.sysrq = 1 net.ipv4.ip_forward = 0 net.ipv4.tcp_syncookies = 1 net.ipv6.conf.all.forwarding = 0
So, if you don't like the change done by YaST and want to revert it call:
# snapper undochange 2..3 create:0 modify:1 delete:0 undoing change... undoing change done
But note that snapper does not tell the kernel about the change like YaST did so you must either do so yourself or reboot.
Adding /home To Snapper
During installation YaST does not setup a snapper config for /home. We can do so manually:
# snapper -c home create-config /home
Whenever you want to use snapper for /home you must provide the option -c home.
Now you can see what files have changed since the last hourly snapshot:
# snapper -c home list Type | # | Pre # | Date | Cleanup | Description | Userdata -------+---+-------+------------------------------+----------+-------------+--------- single | 0 | | | | current | single | 1 | | Tue 22 Nov 2011 11:30:01 CET | timeline | timeline |
# snapper -c home status 1..0 comparing snapshots... done +... /home/tux/just-married.jpg
The '+' sign means that the file is new.
Manually Creating A Snapshot
If you manually want to create a snapshot use:
# snapper -c home create --description "before the big cleanup"
YaST Snapper GUI
Finally yast2-snapper provides a YaST UI for snapper.
Troubleshooting
In most of cases, user's troubles with Snapper can occur, when user tries to proceed some actions (e.g. incorrectly to create or to delete subvolumes configs) without understanding the 'physics' of Snapper's work. To track it, one should dive a level deeper to reach details.
Let's try to create Snapper's config for /foo and /bar btrfs subvolumes.
snapper -c foo create-config /foo
What really happens, when this command is put?
- Configuration file /etc/snapper/configs/foo is created.
- Folder, where snapshots for /foo subvolume will be stored: /foo/.snapshots/ , is created.
- Configuration file /etc/sysconfig/snapper is updated by changing SNAPPER_CONFIGS parameter: SNAPPER_CONFIGS="foo".
Respectively, when user puts
snapper -c bar create-config /bar
after creating config for /foo subvolume, Snapper's algorithm is the same:
- Configuration file /etc/snapper/configs/bar is created.
- Folder, where snapshots for /bar subvolume will be stored: /bar/.snapshots/ , is created.
- Configuration file /etc/sysconfig/snapper is updated by changing SNAPPER_CONFIGS parameter: SNAPPER_CONFIGS="foo bar".
And so on.
Hence, when
snapper -c foo delete-config
is put to delete configuration for /foo subvolume:
- Configuration file /etc/snapper/configs/foo is deleted.
- Folder, where snapshots for /foo subvolume is stored: /foo/.snapshots/ , is deleted.
- Configuration file /etc/sysconfig/snapper is updated by changing SNAPPER_CONFIGS parameter: SNAPPER_CONFIGS="bar" (foo record is deleted).
WARNING 1: Also remember, that SNAPPER_CONFIGS parameter status is parsed by snapshots cleanup scripts (See 4.5 Automatic Snapshots Cleanup Mechanisms paragraph). And, if it contains orphaned records, snapshots cleanup scripts won't work. And this is risk of disk space full!
WARNING 2: If you do some action manually (e.g. you delete /etc/snapper/configs/foo manually instead of snapper -c foo delete-config command), do not forget to update SNAPPER_CONFIGS parameter in /etc/sysconfig/snapper by manual deleting foo record and to delete manually folder /foo/.snapshots/. Because, if you do something incompletely, Snapper will not be able to work correctly and will exit with error-message. And snapshots cleanup scripts won't work correctly. And this is risk of disk space full!
SUMMARY: Manage your btrfs subvolumes with Snapper tool instead of manual way. This will save you a lot of nerve cells. But if you faced with trouble of btrfs subvolumes management, let you be aware of its mechanisms. Possibly, this will help you to track the nature of problem you faced and solve it easily.
And, of course, do not forget to check Snapper's logs for useful troubleshooting information!
Logs
Snapper logs can be found in /var/log/snapper.log, check this file if you are having issues as it may contain useful troubleshooting information.
Swapfile
Btrfs has received swapfile support in kernel 5.0, however problems will occur when you use snapper - or btrfs for that matter - to take snapshots of your /. The swapfile - even if COW is disabled on the file - will block the snapshot taking process. You may notice in the logs messages like quota rescan or sync failed or if you try to take a snapshot manually snapper will stop with an error message like ERROR: cannot snapshot '@': Text file busy. In this case you need to turn off the swap and delete the swapfile. A workaround for this issue is creating a new subvolume and placing the swapfile there. This requires you to modify your /etc/fstab as well.
Snapper Videos
Greg Kroah-Hartman & SUSE Linux Enterprise Product Manager Demo Snapper (~7min)