Difference between revisions of "Snapper"

From ArchWiki
Jump to: navigation, search
m (Caveats)
(update Pkg/AUR templates)
(Tag: wiki-scripts)
 
(208 intermediate revisions by 39 users not shown)
Line 1: Line 1:
 
[[Category:File systems]]
 
[[Category:File systems]]
 +
[[ja:Snapper]]
 +
[[zh-hans:Snapper]]
 
{{Related articles start}}
 
{{Related articles start}}
 
{{Related|Btrfs}}
 
{{Related|Btrfs}}
 
{{Related|mkinitcpio-btrfs}}
 
{{Related|mkinitcpio-btrfs}}
{{Related|Btrfs - Tips and tricks}}
 
 
{{Related articles end}}
 
{{Related articles end}}
  
[http://snapper.io Snapper] is a tool created by openSUSE's Arvin Schnell that helps with managing snapshots of [[Btrfs]] subvolumes and [[LVM]] volumes. It can create and compare snapshots, revert between snapshots, and supports automatic snapshots timelines.
+
[http://snapper.io Snapper] is a tool created by openSUSE's Arvin Schnell that helps with managing snapshots of [[Btrfs]] subvolumes and thin-provisioned [[LVM]] volumes. It can create and compare snapshots, revert between snapshots, and supports automatic snapshots timelines.
  
 
==Installation==
 
==Installation==
The stable version {{Pkg|snapper}} can be installed from the [https://wiki.archlinux.org/index.php/Official_repositories official repositories].
 
  
The development version {{AUR|snapper-git}} is available on the [[AUR]].
+
[[Install]] the {{pkg|snapper}} package. The development version {{AUR|snapper-git}} is also available.
 +
 
 +
Additionally, a GUI is available with {{AUR|snapper-gui-git}}.
  
 
==Create a new configuration==
 
==Create a new configuration==
To create a new configuration use the {{ic|snapper create-config}} command.
 
  
Example for a subvolume mounted as {{ic|/}}
+
Before creating a snapper configuration for a btrfs subvolume, the subvolume must already exist. If it does not, you should [[Btrfs#Creating a subvolume|create]] it before generating a snapper configuration.
 +
 
 +
To create a new snapper configuration named {{ic|''config''}} for the btrfs subvolume at {{ic|''/path/to/subvolume''}} do:
 +
 
 +
# snapper -c ''config'' create-config ''/path/to/subvolume''
  
{{bc|# snapper -c root create-config /}}
+
This will:
 +
*create a configuration file at {{ic|/etc/snapper/configs/''config''}} based on the default template from {{ic|/etc/snapper/config-templates}}.
 +
*create a subvolume at {{ic|''/path/to/subvolume''/.snapshots}} where future snapshots of for this configuration will be stored. A snapshot's path is {{ic|''/path/to/subvolume''/.snapshots/''#''/snapshot}}, where {{ic|''#''}} is the snapshot number.
 +
*add {{ic|''config''}} to {{ic|SNAPPER_CONFIGS}} in {{ic|/etc/conf.d/snapper}}.
  
This will
+
For example, to create a configuration file for the subvolume mounted at {{ic|/}} do:
*create a config file in {{ic|/etc/snapper/configs/root}} based on the default template from {{ic|/etc/snapper/config-templates}}
 
*create a subvolume {{ic|.snapshots}} in the root of the subvolume (/.snapshots in this case)
 
*add "root" to SNAPPER_CONFIGS in {{ic|/etc/conf.d/snapper}}
 
  
At this point, the configuration is active. If your cron deamon is running, snapper will start taking snapshots every hour.
+
# snapper -c root create-config /
It is advised to review the configuration file and set the desired amount of snapshots to be kept.
 
  
{{Note|For informations on all settings in the config file see {{ic|man snapper-configs}}.}}
+
At this point, the configuration is active. If your [[cron]] daemon is running, snapper will take [[#Automatic timeline snapshots]]. If you do not use a [[cron]] daemon, you will need to use the systemd service and timer. See [[#Enable/disable]].
  
==Automatic timeline snapshots==
+
See [[man page]] for {{ic|snapper-configs}}.
Snapper can create a snapshot timeline with a configurable number of snapshots kept per hour/day/month/year.
 
  
The implementation works as follows:
+
== Take snapshots ==
* By default a snapshot gets created once an hour (cron.hourly)
+
 
* Once a day the "old and unwanted" snapshots get cleaned up by the timeline cleanup algorithm (cron.daily)
+
=== Automatic timeline snapshots ===
 +
 
 +
A snapshot timeline can be created with a configurable number of snapshots kept per hour/day/month/year. When the timeline is enabled, by default a snapshot gets created once an hour. Once a day the snapshots get cleaned up by the timeline cleanup algorithm.
 +
 
 +
==== Enable/disable ====
 +
 
 +
If you have a [[cron]] daemon, this feature should start automatically. To disable it, edit the configuration file corresponding with the subvolume you do not want to have this feature and set:
  
When creating a new configuration with {{ic|snapper create-config}} as shown above, this feature is enabled by default. To disable it, edit the configuration file and set
 
 
{{bc|<nowiki>TIMELINE_CREATE="no"</nowiki>}}
 
{{bc|<nowiki>TIMELINE_CREATE="no"</nowiki>}}
  
The default settings will keep 10 hourly, 10 daily, 10 monthly and 10 yearly snapshots. You may want to change this, especially on busy subvolumes like /. See [[#Caveats]].
+
If you do not have a [[cron]] daemon, you can use the provided systemd units. [[Start]] and [[enable]] {{ic|snapper-timeline.timer}} to start the automatic snapshot timeline. Additionally, [[start]] and [[enable]] {{ic|snapper-cleanup.timer}} to periodically cleanup older snapshots.
  
Here is an example for a configuration with only 7 days of snapshots, no monthly, no yearly ones:
+
==== Set snapshot limits ====
{{hc|/etc/snapper/configs/root|<nowiki>
+
 
# limits for timeline cleanup
+
The default settings will keep 10 hourly, 10 daily, 10 monthly and 10 yearly snapshots. You may want to change this in the configuration, especially on busy subvolumes like {{ic|/}}. See [[#Preventing slowdowns]].
 +
 
 +
Here is an example section of a configuration named {{ic|''config''}} with only 5 hourly snapshots, 7 daily ones, no monthly and no yearly ones:
 +
{{hc|head=/etc/snapper/configs/''config''|output=
 
TIMELINE_MIN_AGE="1800"
 
TIMELINE_MIN_AGE="1800"
 
TIMELINE_LIMIT_HOURLY="5"
 
TIMELINE_LIMIT_HOURLY="5"
 
TIMELINE_LIMIT_DAILY="7"
 
TIMELINE_LIMIT_DAILY="7"
 +
TIMELINE_LIMIT_WEEKLY="0"
 
TIMELINE_LIMIT_MONTHLY="0"
 
TIMELINE_LIMIT_MONTHLY="0"
 
TIMELINE_LIMIT_YEARLY="0"
 
TIMELINE_LIMIT_YEARLY="0"
</nowiki>}}
+
}}
 +
 
 +
==== Change snapshot and cleanup frequencies ====
 +
 
 +
If you are using the provided systemd timers, you can [[edit]] them to change the snapshot and cleanup frequency.
 +
 
 +
For example, when editing the {{ic|snapper-timeline.timer}}, add the following to make the frequency every five minutes, instead of hourly:
 +
 
 +
[Timer]
 +
OnCalendar=
 +
OnCalendar=*:0/5
 +
 
 +
{{Note|The configuration parameter {{ic|TIMELINE_LIMIT_HOURLY}} is tied to the above setting. In the above example it now refers to how many 5-minute snapshots are kept.}}
 +
 
 +
When editing {{ic|snapper-cleanup.timer}}, you need to change {{ic|OnUnitActiveSec}}. To make cleanups occur every hour instead of every day, add:
 +
 
 +
[Timer]
 +
OnUnitActiveSec=1h
 +
 
 +
See [[Systemd/Timers]] and [[Systemd#Drop-in files]].
 +
 
 +
=== Manual snapshots ===
 +
 
 +
==== Simple snapshots ====
 +
 
 +
By default snapper takes snapshots that are of the ''simple'' type, having no special relationship to other snapshots.
 +
 
 +
To take a snapshot of a subvolume manually, do:
 +
 
 +
  # snapper -c ''config'' create --description ''desc''
 +
 
 +
The above command does not use any cleanup algorithm, so the snapshot is stored permanently or until [[#Delete_a_snapshot|deleted]].
 +
 
 +
To set a cleanup algorithm, use the {{ic|-c}} flag after {{ic|create}} and choose either {{ic|number}}, {{ic|timeline}}, {{ic|pre}}, or {{ic|post}}. {{ic|number}} sets snapper to periodically remove snapshots that have exceeded a set number in the configuration file. For example, to create a snaphot that uses the {{ic|number}} algorithm for cleanup do:
 +
 
 +
  # snapper -c ''config'' create -c number
 +
 
 +
See [[#Automatic timeline snapshots]] for how {{ic|timeline}} snapshots work and see [[#Pre/post snapshots]] on how {{ic|pre}} and {{ic|post}} work.
 +
 
 +
==== Pre/post snapshots ====
 +
 
 +
In addition to ''simple'' snapshots, you can also create ''pre/post'' snapshots where ''pre'' snapshots always have a corresponding ''post'' snapshot. The purpose of these pairs is to create a snapshot before and after a system modification.
 +
 
 +
To create a pre/post snapshot pair, first create a ''pre'' snapshot:
 +
 
 +
  # snapper -c ''config'' create -t pre -p
 +
 
 +
Note the number of the snapshot printed, as it is required for the post snapshot.
 +
 
 +
Then perform a system modification (*e.g.*, install a new program, upgrade, etc.).
 +
 
 +
Now create the ''post'' snapshot:
 +
 
 +
  # snapper -c ''config'' create -t post --pre-number ''N''
 +
 
 +
where {{ic|''N''}} is the corresponding ''pre'' snapshot number.
 +
 
 +
An alternative method is to use the {{ic|--command}} flag for {{ic|create}}, which wraps a command with pre/post snapshots:
 +
 
 +
  # snapper -c ''config'' create --command ''cmd''
 +
 
 +
where {{ic|''cmd''}} is the command you wish to wrap with pre/post snapshots.
 +
 
 +
See [[#Wrapping pacman transactions in snapshots]].
 +
 
 +
=== Snapshots on boot ===
 +
 
 +
To have snapper take a snapshot of the {{ic|root}} configuration, [[enable]] {{ic|snapper-boot.timer}}.
 +
 
 +
== List snapshots ==
 +
 
 +
To list snapshots taken for a given configuration ''config'' do:
 +
 
 +
  # snapper -c ''config'' list
 +
 
 +
== List configurations ==
 +
 
 +
To list all [[#Create a new configuration|configurations]] you have created do:
 +
 
 +
  # snapper list-configs
 +
 
 +
== Delete a snapshot ==
 +
 
 +
To delete a snapshot number {{ic|''N''}} do:
 +
 
 +
  # snapper -c ''config'' delete ''N''
 +
 
 +
Multiple snapshots can be deleted at one time. For example, to delete snapshots 65 and 70 of the root configuration do:
 +
 
 +
  # snapper -c root delete 65 70
 +
 
 +
{{Note|When deleting a pre snapshot, you should always delete its corresponding post snapshot and vice versa.}}
 +
 
 +
==Access for non-root users==
 +
Each config is created with the root user, and by default, only root can see and access it.
 +
 
 +
To be able to list the snapshots for a given config for a specific user, simply change the value of {{ic|ALLOW_USERS}} in your {{ic|/etc/snapper/configs/''config''}} file. You should now be able to run {{ic|snapper -c ''config'' list}} as a normal user.
 +
 
 +
Eventually, you want to be able to browse the {{ic|.snapshots}} directory with a user, but the owner of this directory must stay root. Therefore, you should change the group owner by a group containing the user you are interested in, such as {{ic|users}} for example:
 +
 
 +
# chmod a+rx .snapshots
 +
# chown :users .snapshots
 +
 
 +
== Tips and tricks ==
 +
 
 +
=== Wrapping pacman transactions in snapshots===
 +
 
 +
There are a couple of packages used for automatically creating snapshots upon a pacman transaction:
 +
 
 +
* {{App|pacupg|"Script that wraps package and AUR upgrades in btrfs snapshots and provides an easy way to roll them back."|https://github.com/crossroads1112/bin/tree/master/pacupg|{{AUR|pacupg}}}}
 +
* {{App|snap-pac|"Makes pacman automatically use snapper to create [[#Pre/post snapshots]] like openSUSE's YaST". Uses [[Pacman#Hooks]].|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}
 +
* {{App|snap-pac-grub|"Additionally updates GRUB entries for {{AUR|grub-btrfs}} after {{pkg|snap-pac}} made the snapshots. Also uses [[Pacman#Hooks]].|{{AUR|snap-pac-grub}}|{{aur|snap-pac-grub}}}}
 +
* {{App|snp|wrap any shell command in a snapper pre-post snapshot, e.g.  {{ic|$ snp pacman -Syyu}}|https://gist.github.com/erikw/5229436|}}
 +
 
 +
==== Backup non-btrfs boot partition on pacman transactions ====
 +
 
 +
If your {{ic|/boot}} partition is on a non btrfs filesystem (e.g. an [[ESP]]) you are not able to do snapper backups with it. You can copy the boot partition automatically on a kernel update to your btrfs root with a hook. This also plays nice together with {{Pkg|snap-pac}}.
 +
{{hc|1=/usr/share/libalpm/hooks/50_bootbackup.hook|2=
 +
[Trigger]
 +
Operation = Upgrade
 +
Operation = Install
 +
Operation = Remove
 +
Type = Package
 +
Target = linux*
 +
 
 +
[Action]
 +
Depends = rsync
 +
Description = Backing up /boot...
 +
When = PreTransaction
 +
Exec = /usr/bin/rsync -a --delete /boot /.bootbackup
 +
}}
 +
 
 +
=== Incremental backup to external drive ===
 +
 
 +
The following packages use {{ic|btrfs send}} and {{ic|btrfs receive}} to send backups incrementally to an external drive. Refer to their documenation to see differences in implementation, features, and requirements.
 +
 
 +
* {{App|buttersink|"Buttersink is like rsync for btrfs snapshots."|https://github.com/AmesCornish/buttersink.git|{{AUR|buttersink-git}}}}
 +
* {{App|snap-sync|"Use snapper snapshots to backup to external drive."|https://github.com/wesbarnett/snap-sync.git|{{Pkg|snap-sync}}}}
 +
* {{App|snapsync|"A synchronization tool for snapper"|https://github.com/doudou/snapsync|{{AUR|ruby-snapsync}}}}
 +
 
 +
===Suggested filesystem layout===
 +
 
 +
{{Note|1=The following layout is intended ''not'' to be used with {{ic|snapper rollback}}, but is intended to mitigate inherit problems with restoring {{ic|/}} with that command. See [https://bbs.archlinux.org/viewtopic.php?id=194491 this forum thread].}}
 +
 
 +
Here is a suggested file system layout for easily restoring your {{ic|/}} to a previous snapshot:
 +
 
 +
subvolid=5
 +
    |
 +
    ├── @
 +
    |      |
 +
    |      ├── /usr
 +
    |      |
 +
    |      ├── /bin
 +
    |      |
 +
    |      ├── /.snapshots
 +
    |      |
 +
    |      ├── ...
 +
    |
 +
    ├── @snapshots
 +
    |
 +
    └── @...
 +
 
 +
Where {{ic|/.snapshots}} is a mountpoint for {{ic|@snapshots}}. {{ic|@...}} are subvolumes that you want to keep separate from the subvolume you will be mounting as {{ic|/}} ({{ic|@}}). When taking a snapshot of {{ic|/}}, these other subvolumes are not included. However, you can still snapshot these other subvolumes separately by creating other snapper configurations for them. Additionally, if you were to restore your system to a previous snapshots of {{ic|/}}, these other subvolumes will remain unaffected.
 +
 
 +
For example if you want to be able restore {{ic|/}} to a previous snapshot but keep your {{ic|/home}} intact, you should create a subvolume that will be mounted at {{ic|/home}}. See [[Btrfs#Mounting subvolumes]].
 +
 
 +
This layout allows the snapper utility to take regular snapshots of {{ic|/}}, while at the same time making it easy to restore {{ic|/}} from an Arch Live CD if it becomes unbootable.
 +
 
 +
In this sceneario, after the initial setup, snapper needs no changes, and will work as expected.
 +
 
 +
{{Note|Even if a subvolume is nested below {{ic|@}}, a snapshot of {{ic|/}} will ''not'' include it. Be sure to set up snapper for any additional subvolumes you want to keep snapshots of besides the one mounted at {{ic|/}}.}}
 +
 
 +
====Configuration of snapper and mount point====
 +
 
 +
Make sure {{ic|/.snapshots}} is ''not'' mounted and does ''not'' exist as folder.
 +
  # umount /.snapshots
 +
  # rm -r /.snapshots
 +
 
 +
Then [[#Create a new configuration]] for {{ic|/}}.
 +
 
 +
Now [[mount]] {{ic|@snapshots}} to {{ic|/.snapshots}}.
 +
For example, for a file system located on {{ic|/dev/sda1}}:
 +
  # mount -o subvol=@snapshots /dev/sda1 /.snapshots
 +
To make this mount permanent, add an entry to your [[fstab]].
 +
 
 +
Or if you have an existing fstab entry remount the snapshot subvolume:
 +
  # mount -a
 +
 
 +
Give the folder {{ic|750}} [[Permissions#Numeric_method|permissions]].
 +
 
 +
This will make all snapshots that snapper creates be stored outside of the {{ic|@}} subvolume, so that {{ic|@}} can easily be replaced anytime without losing the snapper snapshots.
 +
 
 +
====Restoring {{ic|/}} to a previous snapshot of {{ic|@}} ====
 +
 
 +
If you ever want to restore {{ic|/}} using one of snapper's snapshots, first boot into a live Arch Linux USB/CD.
 +
 
 +
[[Mount]] the toplevel subvolume (subvolid=5). That is, omit any {{ic|subvolid}} mount flags.
 +
 
 +
Find the snapshot you want to recover in {{ic|/mnt/@snapshots/*/info.xml}}.
 +
{{Tip| You can use {{ic|vi}} to easily browse through each file:
 +
  # vi /mnt/@snapshots/*/info.xml
 +
Use {{ic|:n}} to see the next file and {{ic|:rew}} to go back to the first file.}}
 +
 
 +
Browse through the {{ic|<description>}} tags and the {{ic|<date>}} tags, and when you find the snapshot you wish to restore, remember the {{ic|<num>}} number.
 +
 
 +
Now, move {{ic|@}} to another location (''e.g.'' {{ic|/@.broken}}) to save a copy of the current system. Alternatively, simply delete {{ic|@}} using {{ic|btrfs subvolume delete}}.
 +
 
 +
Create a read-write snapshot of the read-only snapshot snapper took:
 +
 
 +
  # btrfs subvol snapshot /mnt/@snapshots/''#''/snapshot /mnt/@
 +
 
 +
Where {{ic|''#''}} is the number of the snapper snapshot you wish to restore. Your {{ic|/}} has now been restore to the previous snapshot. Now just simply reboot.
 +
 
 +
===Deleting files from snapshots===
 +
 
 +
If you want to delete a specific file or folder from past snapshots without deleting the snapshots themselves, [https://pypi.python.org/pypi/snapperS snapperS] is a script that adds this functionality to Snapper. This script can also be used to manipulate past snapshots in a number of other ways that Snapper does not currently support.
  
The {{ic|snapper -c root list}} output after some weeks:
+
If you want to remove a file without using an extra script, you just need to [http://unix.stackexchange.com/a/149933/3587 make your snapshot subvolume read-write], which you can do with:
  
{{hc|# snapper -c root list|<nowiki>
+
# btrfs property set /path/to/.snapshots/<snapshot_num>/snapshot ro false
Type  | #    | Pre # | Date                    | User | Cleanup  | Description | Userdata
 
-------+------+-------+--------------------------+------+----------+-------------+---------
 
single | 0    |      |                          | root |          | current    |                                                                           
 
single | 3053 |      | Tue Oct 22 00:01:02 2013 | root | timeline | timeline    |                                                                           
 
single | 3077 |      | Wed Oct 23 00:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3101 |      | Thu Oct 24 00:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3125 |      | Fri Oct 25 00:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3149 |      | Sat Oct 26 00:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3173 |      | Sun Oct 27 00:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3197 |      | Sun Oct 27 23:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3198 |      | Mon Oct 28 00:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3199 |      | Mon Oct 28 01:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3200 |      | Mon Oct 28 02:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3201 |      | Mon Oct 28 03:01:02 2013 | root | timeline | timeline    |                                                                           
 
single | 3202 |      | Mon Oct 28 04:01:01 2013 | root | timeline | timeline    |                                                                           
 
single | 3203 |      | Mon Oct 28 05:01:02 2013 | root | timeline | timeline    |       
 
single | 3204 |      | Mon Oct 28 06:01:01 2013 | root | timeline | timeline    |       
 
single | 3205 |      | Mon Oct 28 07:01:02 2013 | root | timeline | timeline    |       
 
single | 3206 |      | Mon Oct 28 08:01:01 2013 | root | timeline | timeline    |       
 
single | 3207 |      | Mon Oct 28 09:01:01 2013 | root | timeline | timeline    |       
 
single | 3208 |      | Mon Oct 28 10:01:01 2013 | root | timeline | timeline    |       
 
single | 3209 |      | Mon Oct 28 11:01:01 2013 | root | timeline | timeline    |       
 
single | 3210 |      | Mon Oct 28 12:01:01 2013 | root | timeline | timeline    |       
 
single | 3211 |      | Mon Oct 28 13:01:01 2013 | root | timeline | timeline    |       
 
single | 3212 |      | Mon Oct 28 14:01:01 2013 | root | timeline | timeline    |       
 
single | 3213 |      | Mon Oct 28 15:01:01 2013 | root | timeline | timeline    |       
 
single | 3214 |      | Mon Oct 28 16:01:01 2013 | root | timeline | timeline    |       
 
single | 3215 |      | Mon Oct 28 17:01:01 2013 | root | timeline | timeline    |       
 
single | 3216 |      | Mon Oct 28 18:01:01 2013 | root | timeline | timeline    |       
 
single | 3217 |      | Mon Oct 28 19:01:01 2013 | root | timeline | timeline    |       
 
single | 3218 |      | Mon Oct 28 20:01:01 2013 | root | timeline | timeline    |
 
</nowiki>}}
 
  
== Tips and Tricks ==
+
verify that <tt>ro=false</tt>:
===Pre-post snapshots with pacman===
 
Snapper can create snapshots "tagged" as pre or post snapshots. This is handy when it comes to system upgrades.
 
Using {{ic|<nowiki>NUMBER_CLEANUP="yes"</nowiki>}} those can get cleaned up after a configurable number of snapshots using the number cleanup algorithm - see {{ic|man snapper}} and {{ic|man snapper-configs}} for details.
 
  
To use this feature with pacman, you will need some wrapper script. User [https://aur.archlinux.org/account/erikw/ erikw] created one for this purpose called [https://gist.github.com/erikw/5229436 snp].
+
# btrfs property get /path/to/.snapshots/<snapshot_num>/snapshot
 +
ro=false
  
Download it, adjust the logfile location to your liking, put it somewhere in your {{ic|$PATH}} (e.g. {{ic|/usr/local/bin/}}) and make it executable. Usage example:
+
You can now modify files in <tt>/path/to/.snapshots/<snapshot_num>/snapshot</tt> like normalYou can use a shell loop to work on your snapshots in bulk.
  # snp pacman -Syu
 
  
If you like, you can create an [[Bash#Aliases|alias]], similar to [[Pacman Tips#Shortcuts|plain pacman aliases]]:
+
=== Preventing slowdowns ===
alias sysupgrade='snp pacman -Syu'
 
  
Then you can do system upgrades with pre-post snapshots using
+
Keeping many of snapshots for a large timeframe on a busy filesystem like {{ic|/}}, where many system updates happen over time, can cause serious slowdowns. You can prevent it by:
# sysupgrade
+
* [[Btrfs#Creating_a_subvolume|Creating]] subvolumes for things that are not worth being snapshotted, like {{ic|/var/cache/pacman/pkg}}, {{ic|/var/abs}}, {{ic|/var/tmp}}, and {{ic|/srv}}.
 +
* Editing the default settings for hourly/daily/monthly/yearly snapshots when using [[#Automatic timeline snapshots]].
 +
 
 +
==== updatedb ====
 +
 
 +
By default, {{ic|updatedb}} will also index the {{ic|.snapshots}} directory created by snapper, which can cause serious slowdown and excessive memory usage if you have many snapshots. You can prevent {{ic|updatedb}} from indexing over it by editing:
 +
{{hc|/etc/updatedb.conf|2=PRUNENAMES = ".snapshots"}}
 +
 
 +
=== Preserving log files ===
 +
 
 +
It's recommended to create a subvolume for {{ic|/var/log}} so that snapshots of {{ic|/}} exclude it. That way if a snapshot of {{ic|/}} is restored your log files will not also be reverted to the previous state. This make it easier to troubleshoot.
 +
 
 +
=== Cleanup based on disk usage ===
 +
 
 +
{{Expansion|See [http://snapper.io/2016/05/18/space-aware-cleanup.html] for ideas.}}
  
 
== Troubleshooting ==
 
== Troubleshooting ==
 +
===Snapper logs===
 
Snapper writes all activity to {{ic|/var/log/snapper.log}} - check this file first if you think something goes wrong.
 
Snapper writes all activity to {{ic|/var/log/snapper.log}} - check this file first if you think something goes wrong.
  
If you have issues with hourly/daily/weekly snapshots, the most common cause for this so far has been that the cronie service (or whatever cron daemon you're using) wasn't running.
+
If you have issues with hourly/daily/weekly snapshots, the most common cause for this so far has been that the cronie service (or whatever cron daemon you are using) was not running.
  
== Caveats ==
+
===IO error===
 +
If you get an 'IO Error' when trying to create a snapshot please make sure that the [https://bbs.archlinux.org/viewtopic.php?id=164404 .snapshots] directory associated to the subvolume you are trying to snapshot is a subvolume by itself.
  
=== Snapshots of root filesystem ===
+
Another possible cause is that .snapshots directory does not have root as an owner (You will find {{ic|Btrfs.cc(openInfosDir):219 - .snapshots must have owner root}} in the {{ic|/var/log/snapper.log}}).
Many snapshots on a large timeframe of a busy filesystem (like {{ic|/}}, where many system updates happen over time) can cause serious slowdowns. You can prevent it by:
 
* Create subvolumes for things that are not worth to be snapshotted, like {{ic|/var/cache/pacman/pkg}} and {{ic|/var/abs}}.
 
* Edit the default settings for hourly/daily/monthy/yearly snapshots when using [[#Automatic timeline snapshots]].
 
  
=== updatedb ===
+
== See also ==
By default, {{ic|updatedb}} will also index the {{ic|.snapshots}} directory created by snapper, which can cause serious slowdown and excessive memory usage if you have many snapshots. You can prevent {{ic|updatedb}} from indexing over it by editing:
+
* [http://snapper.io/ Snapper homepage]
{{hc|/etc/updatedb.conf|2=PRUNENAMES = ".snapshots"}}
+
* [https://en.opensuse.org/Portal:Snapper openSUSE Snapper portal]
 +
* [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs homepage]
 +
* [https://www.linux.com/news/enterprise/systems-management/878490-snapper-suses-ultimate-btrfs-snapshot-manager/ Linux.com: Snapper: SUSE's Ultimate Btrfs Snapshot Manager]

Latest revision as of 13:32, 12 May 2018

Snapper is a tool created by openSUSE's Arvin Schnell that helps with managing snapshots of Btrfs subvolumes and thin-provisioned LVM volumes. It can create and compare snapshots, revert between snapshots, and supports automatic snapshots timelines.

Installation

Install the snapper package. The development version snapper-gitAUR is also available.

Additionally, a GUI is available with snapper-gui-gitAUR.

Create a new configuration

Before creating a snapper configuration for a btrfs subvolume, the subvolume must already exist. If it does not, you should create it before generating a snapper configuration.

To create a new snapper configuration named config for the btrfs subvolume at /path/to/subvolume do:

# snapper -c config create-config /path/to/subvolume

This will:

  • create a configuration file at /etc/snapper/configs/config based on the default template from /etc/snapper/config-templates.
  • create a subvolume at /path/to/subvolume/.snapshots where future snapshots of for this configuration will be stored. A snapshot's path is /path/to/subvolume/.snapshots/#/snapshot, where # is the snapshot number.
  • add config to SNAPPER_CONFIGS in /etc/conf.d/snapper.

For example, to create a configuration file for the subvolume mounted at / do:

# snapper -c root create-config /

At this point, the configuration is active. If your cron daemon is running, snapper will take #Automatic timeline snapshots. If you do not use a cron daemon, you will need to use the systemd service and timer. See #Enable/disable.

See man page for snapper-configs.

Take snapshots

Automatic timeline snapshots

A snapshot timeline can be created with a configurable number of snapshots kept per hour/day/month/year. When the timeline is enabled, by default a snapshot gets created once an hour. Once a day the snapshots get cleaned up by the timeline cleanup algorithm.

Enable/disable

If you have a cron daemon, this feature should start automatically. To disable it, edit the configuration file corresponding with the subvolume you do not want to have this feature and set:

TIMELINE_CREATE="no"

If you do not have a cron daemon, you can use the provided systemd units. Start and enable snapper-timeline.timer to start the automatic snapshot timeline. Additionally, start and enable snapper-cleanup.timer to periodically cleanup older snapshots.

Set snapshot limits

The default settings will keep 10 hourly, 10 daily, 10 monthly and 10 yearly snapshots. You may want to change this in the configuration, especially on busy subvolumes like /. See #Preventing slowdowns.

Here is an example section of a configuration named config with only 5 hourly snapshots, 7 daily ones, no monthly and no yearly ones:

/etc/snapper/configs/config
TIMELINE_MIN_AGE="1800"
TIMELINE_LIMIT_HOURLY="5"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="0"
TIMELINE_LIMIT_MONTHLY="0"
TIMELINE_LIMIT_YEARLY="0"

Change snapshot and cleanup frequencies

If you are using the provided systemd timers, you can edit them to change the snapshot and cleanup frequency.

For example, when editing the snapper-timeline.timer, add the following to make the frequency every five minutes, instead of hourly:

[Timer]
OnCalendar=
OnCalendar=*:0/5
Note: The configuration parameter TIMELINE_LIMIT_HOURLY is tied to the above setting. In the above example it now refers to how many 5-minute snapshots are kept.

When editing snapper-cleanup.timer, you need to change OnUnitActiveSec. To make cleanups occur every hour instead of every day, add:

[Timer]
OnUnitActiveSec=1h

See Systemd/Timers and Systemd#Drop-in files.

Manual snapshots

Simple snapshots

By default snapper takes snapshots that are of the simple type, having no special relationship to other snapshots.

To take a snapshot of a subvolume manually, do:

 # snapper -c config create --description desc

The above command does not use any cleanup algorithm, so the snapshot is stored permanently or until deleted.

To set a cleanup algorithm, use the -c flag after create and choose either number, timeline, pre, or post. number sets snapper to periodically remove snapshots that have exceeded a set number in the configuration file. For example, to create a snaphot that uses the number algorithm for cleanup do:

 # snapper -c config create -c number

See #Automatic timeline snapshots for how timeline snapshots work and see #Pre/post snapshots on how pre and post work.

Pre/post snapshots

In addition to simple snapshots, you can also create pre/post snapshots where pre snapshots always have a corresponding post snapshot. The purpose of these pairs is to create a snapshot before and after a system modification.

To create a pre/post snapshot pair, first create a pre snapshot:

 # snapper -c config create -t pre -p

Note the number of the snapshot printed, as it is required for the post snapshot.

Then perform a system modification (*e.g.*, install a new program, upgrade, etc.).

Now create the post snapshot:

 # snapper -c config create -t post --pre-number N

where N is the corresponding pre snapshot number.

An alternative method is to use the --command flag for create, which wraps a command with pre/post snapshots:

 # snapper -c config create --command cmd

where cmd is the command you wish to wrap with pre/post snapshots.

See #Wrapping pacman transactions in snapshots.

Snapshots on boot

To have snapper take a snapshot of the root configuration, enable snapper-boot.timer.

List snapshots

To list snapshots taken for a given configuration config do:

 # snapper -c config list

List configurations

To list all configurations you have created do:

 # snapper list-configs

Delete a snapshot

To delete a snapshot number N do:

 # snapper -c config delete N

Multiple snapshots can be deleted at one time. For example, to delete snapshots 65 and 70 of the root configuration do:

 # snapper -c root delete 65 70
Note: When deleting a pre snapshot, you should always delete its corresponding post snapshot and vice versa.

Access for non-root users

Each config is created with the root user, and by default, only root can see and access it.

To be able to list the snapshots for a given config for a specific user, simply change the value of ALLOW_USERS in your /etc/snapper/configs/config file. You should now be able to run snapper -c config list as a normal user.

Eventually, you want to be able to browse the .snapshots directory with a user, but the owner of this directory must stay root. Therefore, you should change the group owner by a group containing the user you are interested in, such as users for example:

# chmod a+rx .snapshots
# chown :users .snapshots

Tips and tricks

Wrapping pacman transactions in snapshots

There are a couple of packages used for automatically creating snapshots upon a pacman transaction:

  • pacupg — "Script that wraps package and AUR upgrades in btrfs snapshots and provides an easy way to roll them back."
https://github.com/crossroads1112/bin/tree/master/pacupg || pacupgAUR
https://github.com/wesbarnett/snap-pac || snap-pac
snap-pac-grubAUR || snap-pac-grubAUR
  • snp — wrap any shell command in a snapper pre-post snapshot, e.g. $ snp pacman -Syyu
https://gist.github.com/erikw/5229436 ||

Backup non-btrfs boot partition on pacman transactions

If your /boot partition is on a non btrfs filesystem (e.g. an ESP) you are not able to do snapper backups with it. You can copy the boot partition automatically on a kernel update to your btrfs root with a hook. This also plays nice together with snap-pac.

/usr/share/libalpm/hooks/50_bootbackup.hook
[Trigger]
Operation = Upgrade
Operation = Install
Operation = Remove
Type = Package
Target = linux*

[Action]
Depends = rsync
Description = Backing up /boot...
When = PreTransaction
Exec = /usr/bin/rsync -a --delete /boot /.bootbackup

Incremental backup to external drive

The following packages use btrfs send and btrfs receive to send backups incrementally to an external drive. Refer to their documenation to see differences in implementation, features, and requirements.

  • buttersink — "Buttersink is like rsync for btrfs snapshots."
https://github.com/AmesCornish/buttersink.git || buttersink-gitAUR
  • snap-sync — "Use snapper snapshots to backup to external drive."
https://github.com/wesbarnett/snap-sync.git || snap-sync
  • snapsync — "A synchronization tool for snapper"
https://github.com/doudou/snapsync || ruby-snapsyncAUR

Suggested filesystem layout

Note: The following layout is intended not to be used with snapper rollback, but is intended to mitigate inherit problems with restoring / with that command. See this forum thread.

Here is a suggested file system layout for easily restoring your / to a previous snapshot:

subvolid=5
   |
   ├── @
   |       |
   |       ├── /usr
   |       |
   |       ├── /bin
   |       |
   |       ├── /.snapshots
   |       |
   |       ├── ...
   |
   ├── @snapshots
   |
   └── @...

Where /.snapshots is a mountpoint for @snapshots. @... are subvolumes that you want to keep separate from the subvolume you will be mounting as / (@). When taking a snapshot of /, these other subvolumes are not included. However, you can still snapshot these other subvolumes separately by creating other snapper configurations for them. Additionally, if you were to restore your system to a previous snapshots of /, these other subvolumes will remain unaffected.

For example if you want to be able restore / to a previous snapshot but keep your /home intact, you should create a subvolume that will be mounted at /home. See Btrfs#Mounting subvolumes.

This layout allows the snapper utility to take regular snapshots of /, while at the same time making it easy to restore / from an Arch Live CD if it becomes unbootable.

In this sceneario, after the initial setup, snapper needs no changes, and will work as expected.

Note: Even if a subvolume is nested below @, a snapshot of / will not include it. Be sure to set up snapper for any additional subvolumes you want to keep snapshots of besides the one mounted at /.

Configuration of snapper and mount point

Make sure /.snapshots is not mounted and does not exist as folder.

 # umount /.snapshots
 # rm -r /.snapshots

Then #Create a new configuration for /.

Now mount @snapshots to /.snapshots. For example, for a file system located on /dev/sda1:

 # mount -o subvol=@snapshots /dev/sda1 /.snapshots

To make this mount permanent, add an entry to your fstab.

Or if you have an existing fstab entry remount the snapshot subvolume:

 # mount -a

Give the folder 750 permissions.

This will make all snapshots that snapper creates be stored outside of the @ subvolume, so that @ can easily be replaced anytime without losing the snapper snapshots.

Restoring / to a previous snapshot of @

If you ever want to restore / using one of snapper's snapshots, first boot into a live Arch Linux USB/CD.

Mount the toplevel subvolume (subvolid=5). That is, omit any subvolid mount flags.

Find the snapshot you want to recover in /mnt/@snapshots/*/info.xml.

Tip: You can use vi to easily browse through each file:
 # vi /mnt/@snapshots/*/info.xml
Use :n to see the next file and :rew to go back to the first file.

Browse through the <description> tags and the <date> tags, and when you find the snapshot you wish to restore, remember the <num> number.

Now, move @ to another location (e.g. /@.broken) to save a copy of the current system. Alternatively, simply delete @ using btrfs subvolume delete.

Create a read-write snapshot of the read-only snapshot snapper took:

 # btrfs subvol snapshot /mnt/@snapshots/#/snapshot /mnt/@

Where # is the number of the snapper snapshot you wish to restore. Your / has now been restore to the previous snapshot. Now just simply reboot.

Deleting files from snapshots

If you want to delete a specific file or folder from past snapshots without deleting the snapshots themselves, snapperS is a script that adds this functionality to Snapper. This script can also be used to manipulate past snapshots in a number of other ways that Snapper does not currently support.

If you want to remove a file without using an extra script, you just need to make your snapshot subvolume read-write, which you can do with:

# btrfs property set /path/to/.snapshots/<snapshot_num>/snapshot ro false

verify that ro=false:

# btrfs property get /path/to/.snapshots/<snapshot_num>/snapshot
ro=false

You can now modify files in /path/to/.snapshots/<snapshot_num>/snapshot like normal. You can use a shell loop to work on your snapshots in bulk.

Preventing slowdowns

Keeping many of snapshots for a large timeframe on a busy filesystem like /, where many system updates happen over time, can cause serious slowdowns. You can prevent it by:

  • Creating subvolumes for things that are not worth being snapshotted, like /var/cache/pacman/pkg, /var/abs, /var/tmp, and /srv.
  • Editing the default settings for hourly/daily/monthly/yearly snapshots when using #Automatic timeline snapshots.

updatedb

By default, updatedb will also index the .snapshots directory created by snapper, which can cause serious slowdown and excessive memory usage if you have many snapshots. You can prevent updatedb from indexing over it by editing:

/etc/updatedb.conf
PRUNENAMES = ".snapshots"

Preserving log files

It's recommended to create a subvolume for /var/log so that snapshots of / exclude it. That way if a snapshot of / is restored your log files will not also be reverted to the previous state. This make it easier to troubleshoot.

Cleanup based on disk usage

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: See [1] for ideas. (Discuss in Talk:Snapper#)

Troubleshooting

Snapper logs

Snapper writes all activity to /var/log/snapper.log - check this file first if you think something goes wrong.

If you have issues with hourly/daily/weekly snapshots, the most common cause for this so far has been that the cronie service (or whatever cron daemon you are using) was not running.

IO error

If you get an 'IO Error' when trying to create a snapshot please make sure that the .snapshots directory associated to the subvolume you are trying to snapshot is a subvolume by itself.

Another possible cause is that .snapshots directory does not have root as an owner (You will find Btrfs.cc(openInfosDir):219 - .snapshots must have owner root in the /var/log/snapper.log).

See also