263 lines
8.6 KiB
Groff
263 lines
8.6 KiB
Groff
'\" t
|
|
.TH SNAP-PAC 8 2021-01-29 SNAP-PAC
|
|
.SH NAME
|
|
snap-pac \- Pacman hooks that use snapper to create pre/post btrfs snapshots
|
|
like openSUSE's YaST
|
|
|
|
.SH DESCRIPTION
|
|
|
|
This is a set of \fIpacman\fR hooks and script that causes \fIsnapper\fR to
|
|
automatically take a pre and post snapshot before and after pacman transactions,
|
|
similar to how YaST does with OpenSuse. This provides a simple way to undo
|
|
changes to a system after a pacman transaction.
|
|
|
|
Because these are pacman hooks, it doesn't matter how you call pacman—whether
|
|
directly, through an AUR helper, or using an alias—snapper will create the
|
|
snapshots when pacman installs, upgrades, or removes a package. The pacman
|
|
command used is logged in the snapper description for the snapshots.
|
|
Additionally the snapshot numbers are output to the screen and to the pacman log
|
|
for each snapper configuration during the pacman transaction, so that the user can
|
|
easily find which changes he or she may want to revert.
|
|
|
|
To undo changes from a pacman transaction, use \fIsnapper undochange\fR. See
|
|
\fBsnapper\fR(8) and \fBEXAMPLES\fR.
|
|
|
|
If you have severe breakage—like snapper is gone for some reason and you can't
|
|
get it back—you'll have to resort to more extreme methods, such as taking a
|
|
snapshot of the pre snapshot and making it the default subvolume or mounting it
|
|
as \fI/\fR. Most likely you'll need to use a live USB to get into a chroot
|
|
environment to do any of these things. Snapper has a snapper rollback feature,
|
|
but your setup has to be properly configured to use it. The exact procedure
|
|
depends on your specific setup. Be careful.
|
|
|
|
.SH CONFIGURATION
|
|
Configuration is done via configuration files. The defaults of the
|
|
following should be suitable for most users, so you may not need to do
|
|
any configuration at all. Follow the pattern of bash shell variables
|
|
(VAR=setting) in each configuration file below. Comments can be added
|
|
by adding \fI#\fR before the comment. Example configuration files are
|
|
located at \fI/etc/snap-pac.conf.example\fR and
|
|
\fI/etc/snap-pac/root.conf.example\fR.
|
|
|
|
The following settings can be changed in the main snap-pac configuration file
|
|
\fI/etc/snap-pac.conf\fR:
|
|
|
|
\fBABORT_ON_FAIL=\fR\fB\fIyes\fR\fR\fB or \fR\fB\fIno\fR\fR
|
|
.RS 4
|
|
When set to "yes" this causes pacman to abort a transaction if the snap-pac pre
|
|
hook fails. This prevents an upgrade/installation/removal from occurring if a
|
|
pre snapshot cannot be performed.
|
|
|
|
Default is "no".
|
|
.RE
|
|
|
|
\fBDESC_LIMIT=\fR\fB\fIinteger\fR\fR
|
|
.RS 4
|
|
Number of characters to limit length of descriptions used for snapper.
|
|
|
|
Default is "72".
|
|
.RE
|
|
|
|
The following are possible settings used on each specific snapper
|
|
configuration you have. To use them, first create the folder
|
|
\fI/etc/snap-pac\fR if it does not already exist. Then create a file
|
|
for the snapper configuration file you want these settings to apply
|
|
to. For example, for the snapper configuration named \fIroot\fR,
|
|
create the file \fI/etc/snap-pac/root.conf\fR. \fIsnap-pac\fR requires
|
|
and expects configuration files to end in \fI.conf\fR.
|
|
|
|
\fBSNAPSHOT=\fR\fB\fIyes\fR\fR\fB or \fR\fB\fIno\fR\fR
|
|
.RS 4
|
|
Perform pacman pre/post snapshots for this configuration. In other
|
|
words, if you want snapper to run before and after a pacman
|
|
transaction, set this to "yes".
|
|
|
|
Default is "no", except for the root configuration which is "yes".
|
|
.RE
|
|
|
|
.BR CLEANUP_ALGORITHM
|
|
.RS 4
|
|
\fBsnapper\fR algorithm used in cleaning up the pacman pre/post snapshots. See
|
|
\fBsnapper\fR(8) for a list of valid options.
|
|
|
|
Default is "number".
|
|
.RE
|
|
|
|
\fBPRE_DESCRIPTION=\fR\fB\fIstring\fR\fR
|
|
.RS 4
|
|
\fBsnapper\fR description used for the pacman pre snapshot.
|
|
|
|
Default is the parent program, usually \fBpacman\fR, that called the snapshot script.
|
|
.RE
|
|
|
|
\fBPOST_DESCRIPTION=\fR\fB\fIstring\fR\fR
|
|
.RS 4
|
|
\fBsnapper\fR description used for the pacman post snapshot.
|
|
|
|
Default is the list of packages that were installed/upgraded/removed
|
|
during the transaction.
|
|
.RE
|
|
|
|
.SH ENVIRONMENT VARIABLES
|
|
|
|
To temporarily prevent snapshots from being performed for a single
|
|
pacman command, set the environment variable \fISNAP_PAC_SKIP\fR. For
|
|
example:
|
|
|
|
.EX
|
|
|
|
$ sudo SNAP_PAC_SKIP=y pacman -Syu
|
|
|
|
.EE
|
|
|
|
|
|
.SH EXAMPLES
|
|
|
|
Here is an example of how the snapshots are created and how to rollback and pacman
|
|
transaction. Here the \fBnano\fR package is installed:
|
|
|
|
.EX
|
|
|
|
# pacman -S nano
|
|
resolving dependencies...
|
|
looking for conflicting packages...
|
|
|
|
Packages (1) nano-2.5.3-1
|
|
|
|
Total Installed Size: 2.14 MiB
|
|
|
|
:: Proceed with installation? [Y/n] Y
|
|
(1/1) checking keys in keyring [######################################] 100%
|
|
(1/1) checking package integrity [######################################] 100%
|
|
(1/1) loading package files [######################################] 100%
|
|
(1/1) checking for file conflicts [######################################] 100%
|
|
(1/1) checking available disk space [######################################] 100%
|
|
:: Running pre-transaction hooks...
|
|
(1/1) Performing snapper pre snapshots for the following configurations...
|
|
=> root: 1033
|
|
:: Processing package changes...
|
|
(1/1) installing nano [######################################] 100%
|
|
:: Running post-transaction hooks...
|
|
(1/1) Performing snapper post snapshots for the following configurations...
|
|
=> root: 1034
|
|
|
|
.EE
|
|
|
|
The snapper snapshot number is given for each snapper configuration that is
|
|
used. This is also logged in pacman's log.
|
|
|
|
Here are the snapshots created before and after the pacman transaction:
|
|
|
|
.EX
|
|
|
|
# snapper -c root list -t pre-post | tail -n 1
|
|
1033 | 1034 | Fri 22 Apr 2016 01:54:13 PM CDT | Fri 22 Apr 2016 01:54:14 PM CDT | pacman -S nano |
|
|
|
|
.EE
|
|
|
|
Here is what changed during the transaction:
|
|
|
|
.EX
|
|
|
|
# snapper -c root status 1033..1034
|
|
+..... /etc/nanorc
|
|
c..... /etc/snapper/.snap-pac-pre
|
|
+..... /usr/bin/nano
|
|
+..... /usr/bin/rnano
|
|
+..... /usr/share/doc/nano
|
|
+..... /usr/share/doc/nano/faq.html
|
|
+..... /usr/share/doc/nano/fr
|
|
+..... /usr/share/doc/nano/fr/nano.1.html
|
|
+..... /usr/share/doc/nano/fr/nanorc.5.html
|
|
+..... /usr/share/doc/nano/fr/rnano.1.html
|
|
|
|
.EE
|
|
|
|
The above output is truncated, but it continues. See the \fBsnapper\fR(8) to
|
|
for what each symbol means. You can also do \fBsnapper diff\fR in the same way.
|
|
|
|
Then, to undo the \fBpacman\fR transaction:
|
|
|
|
.EX
|
|
|
|
# snapper -c root undochange 1033..1034
|
|
create:0 modify:3 delete:100
|
|
|
|
.EE
|
|
|
|
Now nano is no longer installed, along with all the files it changed:
|
|
|
|
.EX
|
|
|
|
$ pacman -Qi nano
|
|
error: package 'nano' was not found
|
|
|
|
.EE
|
|
|
|
.SH TROUBLESHOOTING
|
|
|
|
.SS snap-pac is only taking snapshots of the root configuration.
|
|
That's the default behavior. See \fBCONFIGURATION\fR.
|
|
|
|
.SS No snapshots are being taken when I run pacman.
|
|
No snapper configurations are set up for snap-pac's pacman hooks. By default
|
|
snap-pac will take snapshots for the root configuration and any other
|
|
configuration which has SNAPSHOT set to yes in its configuration file.
|
|
See \fBCONFIGURATION\fR.
|
|
|
|
.SS After restoring snapshot from snap-pac, the pacman database is locked.
|
|
The pre/post snaphots are taken while pacman is running, so this is expected.
|
|
Follow the instructions pacman gives you (e.g., removing the lock file). You can add the
|
|
database lock file to a snapper filter so that snapper won't consider it when performing
|
|
\fBsnapper diff\fR, \fBsnapper status\fR, \fBsnapper undochange\fR, etc. See the
|
|
\fBFilters\fR section in \fBsnapper\fR(8) for more information.
|
|
|
|
|
|
.SH FAQ
|
|
.SS Does snap-pac backup non-btrfs /boot partitions?
|
|
No, but you can add a hook that does it for you. It would be
|
|
something like the following:
|
|
|
|
.EX
|
|
|
|
[Trigger]
|
|
Operation = Upgrade
|
|
Operation = Install
|
|
Operation = Remove
|
|
Type = Package
|
|
Target = linux
|
|
|
|
[Action]
|
|
Description = Backing up /boot...
|
|
When = PreTransaction
|
|
Exec = /usr/bin/rsync -avzq --delete /boot /.bootbackup
|
|
|
|
.EE
|
|
|
|
.SS How do I link old kernel modules automatically when the kernel is upgraded?
|
|
This behavior is no longer a part of this package. Use a pacman hook like the following:
|
|
|
|
[Trigger]
|
|
Operation = Upgrade
|
|
Operation = Install
|
|
Operation = Remove
|
|
Type = Package
|
|
Target = linux
|
|
|
|
[Action]
|
|
Description = Symlinking old kernel modules...
|
|
When = PostTransaction
|
|
Exec = /usr/bin/bash -c "find /usr/lib/modules -xtype l -delete; ln -sv /.snapshots/$(snapper -c root list | awk 'END{print $1}')/snapshot/usr/lib/modules/$(uname -r) /usr/lib/modules/"
|
|
|
|
.SH HOMEPAGE
|
|
https://github.com/wesbarnett/snap-pac
|
|
|
|
.SH AUTHORS
|
|
Wes Barnett <wes@wbarnett.us>
|
|
|
|
.SH SEE ALSO
|
|
.BR alpm-hooks (5),
|
|
.BR snapper (8),
|
|
.BR snapper-configs (5),
|
|
.BR pacman (8)
|
|
|