- 1 Introduction
- 2 Important Details
- 3 Software Requirements
- 4 Snapper Basic Usage
- 5 Snapper Tutorial
- 6 YaST Snapper GUI
- 7 Troubleshooting
- 8 Snapper Videos
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 made 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.
The default behaviour when Snapper is configured to run on root, meaning /, is to exclude every Btrfs subvolume. This the same behaviour as on SUSE Enterprise. This means that if you have the subvolume /srv Snapper will not snapshot 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 behaviour.
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).
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 (single 0) is created automatically.||1. No automatically created config /etc/snapper/configs/root (single 0). Should be created manually by snapper's create-config / command).|
|2. Snapshot (single 1) for root partition (/) is created automatically with name 'first root filesystem'||2. No automatically created single 1 snapshot. Reason: 1. User can create it manually with any name.|
|3. Snapshot (single 2) 'After installation', important=yes, is created automatically.||3. No automatically created single 2 snapshot. 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=no in /etc/snapper/configs/root. This means, that Timeline Snapshots creation is OFF.||5. Default TIMELINE_CREATE=yes in /etc/snapper/configs/root. Timeline Snapshots creation is ON.|
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 create 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.
You always need this package:
If you use YaST2 to install, update or remove packages and want to have snapper automatically create snapshots when you use this tool:
If you use zypper to install, update or remove packages and want to have snapper automatically create snapshots when you use this tool:
If you want to have the ability for advanced btfs snapshot boot menu management:
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)
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
Unless you have a good reason to do otherwise, you should always specify the cleanup algorithm when creating 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:
The following commands assume you will be creating snapshots on the default system configuration (root). As mentioned above, if you want to use the non-default configuration, add the following the the snapshot commands:
Create a snapshot of the type pre and prints the snapshot number. First command needed to create 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
Create a snapshot of the type post paired with the pre snapshot number 30. Second command needed to create 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
Creates 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 2014"
Automatic Snapshots Cleanup Mechanisms
To prevent disk space full, Snapper periodically cleans snapshots up. By default, this period = 1 day.
Automatic snapshots cleanup task can be managed via 2 ways:
- cron scheduler (/etc/cron.daily/suse.de-snapper).
- systemd timer scheduler (snapper-cleanup.timer and snapper-cleanup.service systemd units).
By default, cron mechanism is in use. But there are no road-blocks to use systemd timer mechanism.
Please, do not modify snapshot cleanup scripts manually to prevent incorrect snapshots cleanup behaviour!
All cleanup mechanisms are based on status (yes/no) of these directives from particular partition config-file, stored in /etc/snapper/configs/ path:
- NUMBER_CLEANUP =
- TIMELINE_CLEANUP =
- EMPTY_PRE_POST_CLEANUP =
Delete snapshot 65 for the default (root) configuration:
snapper delete 65
Delete all snapshots (assuming you have no more than 100000 of them) you'd do:
snapper delete 1-100000 (snapper delete number1-number2)
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 | Cleanup | Description | Userdata -------+---+-------+------------------------------+----------+-------------+--------- single | 0 | | | | current | single | 1 | | Tue 22 Nov 2011 10:30:02 CET | 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 a undo tool for YaST. First we run YaST:
# yast2 system_settings
Within YaST enable the SysReq. After you have finished YaST you see two new snapshots:
# snapper list Type | # | Pre # | Date | Cleanup | Description | Userdata -------+---+-------+------------------------------+----------+----------------------+--------- single | 0 | | | | current | single | 1 | | Tue 22 Nov 2011 10:30:02 CET | timeline | timeline | pre | 2 | | Tue 22 Nov 2011 10:41:28 CET | number | yast system_settings | post | 3 | 2 | Tue 22 Nov 2011 10:41:49 CET | number | |
Types of Snapshots
It's time to explain the type of snapshots. Snapper creates a snapshot before and after YaST runs, these snapshots are called pre and post respectively. The post snapshots knows which pre snapshots belongs to it. By having a pre and post snapshot we can see what changes happened to the file system while YaST was running. Single snapshots have no special relationship to other snapshots.
- Installation Snapshot description: https://doc.opensuse.org/documentation/leap/reference/html/book.opensuse.reference/cha.snapper.html#snapper.snapshot-type
- Administrative Snapshot description: https://doc.opensuse.org/documentation/leap/reference/html/book.opensuse.reference/cha.snapper.html#snapper.snapshot-type
- Timeline Snapshots description: https://doc.opensuse.org/documentation/leap/reference/html/book.opensuse.reference/cha.snapper.html#snapper.snapshot-type
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 2011-11-22 10:35:43.355493753 +0100 +++ /.snapshots/3/snapshot/etc/sysctl.conf 2011-11-22 10:41:47.019512185 +0100 @@ -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.
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.
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!
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.