diff --git a/README.md b/README.md index 0e063f6..bcd88d3 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,8 @@ self-explanatory. ## Documentation -See the [documentation here](https://wesbarnett.github.io/snap-pac/). +See the [documentation here](https://wesbarnett.github.io/snap-pac/) or `man 8 snap-pac` +after installation. ## Troubleshooting diff --git a/man8/snap-pac.8 b/man8/snap-pac.8 new file mode 100644 index 0000000..479f5bc --- /dev/null +++ b/man8/snap-pac.8 @@ -0,0 +1,392 @@ +.\" 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\-.tar.gz.sig +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where \fB\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. +.