392 lines
10 KiB
Groff
392 lines
10 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "SNAP-PAC" "8" "Mar 13, 2021" "" "snap-pac"
|
|
.SH NAME
|
|
snap-pac \- Pacman hooks that use snapper to create pre/post btrfs snapshots like openSUSE's YaST
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
|
|
.SH DESCRIPTION
|
|
.sp
|
|
This is a set of \fI\%pacman\fP hooks and script that causes
|
|
\fI\%snapper\fP to automatically take a pre and post snapshot before and
|
|
after pacman transactions, similar to how \fI\%YaST\fP does with
|
|
OpenSuse. This provides a simple way to undo changes to a system after a pacman
|
|
transaction.
|
|
.sp
|
|
Because these are pacman hooks, it doesn\(aqt 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.
|
|
.sp
|
|
To undo changes from a pacman transaction, use \fBsnapper undochange\fP\&. See the \fBsnapper(8)\fP
|
|
for more details as well as examples.
|
|
.sp
|
|
If you have severe breakage—like snapper is gone for some reason and you can\(aqt get it
|
|
back—you\(aqll 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 /. Most likely you\(aqll
|
|
need to use a live USB to get into a chroot environment to do any of these things.
|
|
Snapper has a \fBsnapper rollback\fP feature, but your setup has to be properly configured to
|
|
use it. The exact procedure depends on your specific setup. Be careful.
|
|
.SH INSTALLATION
|
|
.sp
|
|
Install the \fBsnap\-pac\fP package using pacman:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
pacman \-S snap\-pac
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Alternatively download the \fI\%latest release and signature\fP\&. Then, verify the download:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
gpg \-\-verify snap\-pac\-<version>.tar.gz.sig
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
where \fB<version>\fP is the version number you downloaded.
|
|
.sp
|
|
Finally, run:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
make install
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
I have signed the release tarball and commits with my PGP key. Starting with release
|
|
2.2, the tarballs are signed with my key with fingerprint
|
|
\fBF7B28C61944FE30DABEEB0B01070BCC98C18BD66\fP\&.
|
|
.sp
|
|
For previous releases, the key\(aqs fingerprint was
|
|
\fB8535CEF3F3C38EE69555BF67E4B5E45AA3B8C5C3\fP\&.
|
|
.SH CONFIGURATION
|
|
.sp
|
|
Configuration is done via Python ini configuration files. The defaults
|
|
should be suitable for most users, so you may not need to do any configuration at all.
|
|
By default only the \fBroot\fP snapper configuration is snapshotted.
|
|
.sp
|
|
A commented example configuration files is located at \fB/etc/snap\-pac.ini.example\fP\&.
|
|
.sp
|
|
To configure, copy the example configuration file:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
cp /etc/snap\-pac.ini{.example,}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Then edit with your favorite editor. The file is commented and should be
|
|
self\-explanatory.
|
|
.sp
|
|
Each section corresponds with a snapper configuration. Add additional sections to add
|
|
other snapper configurations to be snapshotted. By default, only the root configuration
|
|
is snapshotted. Additionally you can add a section named \fBDEFAULT\fP with options that
|
|
apply to all snapper configurations unless overridden in a later section.
|
|
.sp
|
|
Each section can have the following entries:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fBdesc_limit\fP \- integer; maximum length of description string before being truncated.
|
|
Default: 72
|
|
.IP \(bu 2
|
|
\fBimportant_packages\fP \- list of strings; names of packages that if involved in a pacman
|
|
transaction will add \fBimportant=yes\fP to the snapper userdata for the pair of
|
|
snapshots. Default: []
|
|
.IP \(bu 2
|
|
\fBimportant_commands\fP \- list of strings; parent commands that will add
|
|
\fBimportant=yes\fP to the snapper userdata for the pair of snapshots. Default: []
|
|
.IP \(bu 2
|
|
\fBpre_description\fP \- string; description for the pre snapshot. Default: the parent
|
|
command that called the pacman hook.
|
|
.IP \(bu 2
|
|
\fBpost_description\fP \- string; description for the post snapshot. Default: space
|
|
separated list of packages that were installed, upgraded, or removed.
|
|
.IP \(bu 2
|
|
\fBsnapshot\fP \- boolean; whether or not to snapshot the configuration. Default: True for
|
|
\fBroot\fP configuration; False otherwise.
|
|
.IP \(bu 2
|
|
\fBuserdata\fP \- list of strings; key\-value pairs that will be added to the userdata for
|
|
the pair of snapshots. Default: []
|
|
.UNINDENT
|
|
.SS Environment Variables
|
|
.sp
|
|
To temporarily prevent snapshots from being performed for a single pacman
|
|
command, set the environment variable \fBSNAP_PAC_SKIP\fP\&. For example:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
sudo SNAP_PAC_SKIP=y pacman \-Syu
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH EXAMPLE
|
|
.sp
|
|
Here is an example of how the snapshots are created and how to rollback and pacman
|
|
transaction. Here the nano package is installed:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
pacman \-S nano
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
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
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The snapper snapshot number is given for each snapper configuration that is used. This
|
|
is also logged in pacman\(aqs log.
|
|
.sp
|
|
Here are the snapshots created before and after the pacman transaction:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
snapper \-c root list \-t pre\-post | tail \-n 1
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
1033 | 1034 | Fri 22 Apr 2016 01:54:13 PM CDT | Fri 22 Apr 2016 01:54:14 PM CDT | pacman \-S nano |
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Here is what changed during the transaction:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
snapper \-c root status 1033..1034
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
+..... /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
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The above output is truncated, but it continues. See \fBsnapper(8)\fP to for what each
|
|
symbol means. You can also do \fBsnapper diff\fP in the same way.
|
|
.sp
|
|
Then, to undo the pacman transaction:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
snapper \-c root undochange 1033..1034
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
create:0 modify:3 delete:100
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Now nano is no longer installed, along with all the files it changed:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
pacman \-Qi nano
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
error: package \(aqnano\(aq was not found
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH TROUBLESHOOTING
|
|
.sp
|
|
\fBsnap\-pac is only taking snapshots of the root configuration.\fP
|
|
.sp
|
|
That\(aqs the default behavior. See configuration\&.
|
|
.sp
|
|
\fBNo snapshots are being taken when I run pacman.\fP
|
|
.sp
|
|
No snapper configurations are set up for snap\-pac\(aqs 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 configuration\&.
|
|
.sp
|
|
\fBAfter restoring snapshot from snap\-pac, the pacman database is locked.\fP
|
|
.sp
|
|
The pre/post snaphots are taken while pacman is running, so this is expected. Follow
|
|
the instructions pacman gives you (\fIe.g.\fP, removing the lock file). You can add the
|
|
database lock file to a snapper filter so that snapper won\(aqt consider it when
|
|
performing snapper diff, snapper status, snapper undochange, etc. See the Filters
|
|
section in \fBsnapper(8)\fP for more information.
|
|
.SH FAQ
|
|
.sp
|
|
\fBDoes snap\-pac backup non\-btrfs /boot partitions?\fP
|
|
.sp
|
|
No, but you can add a hook that does it for you. It would be something like the following:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
[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
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBHow do I link old kernel modules automatically when the kernel is upgraded?\fP
|
|
.sp
|
|
This behavior is no longer a part of this package. Use a pacman hook like the following:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
[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 \(aqEND{print $1}\(aq)/snapshot/usr/lib/modules/$(uname \-r) /usr/lib/modules/"
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH AUTHOR
|
|
Wes Barnett
|
|
.SH COPYRIGHT
|
|
2021, Wes Barnett, PhD
|
|
.\" Generated by docutils manpage writer.
|
|
.
|