me/snap-pac
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

add back manpage

Browse source
This commit is contained in:
Wes Barnett 2021-03-13 14:01:23 -05:00
parent 292f1713ad
commit 1ef50ddd42
No known key found for this signature in database
GPG key ID: 1070BCC98C18BD66
2 changed files with 394 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
README.md
View file

@ -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

392
man8/snap-pac.8 Normal file
View file

@ -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\-<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.
.