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

Merge pull request #42 from wesbarnett/feature/man

Browse source 
Don't track changes in manpage since it is generated
This commit is contained in:
Wes Barnett, PhD 2021-04-15 19:37:02 -04:00 • committed by GitHub
commit ef889e198e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 7 additions and 550 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -1,3 +1,4 @@
__pycache__ __pycache__
venv venv
docs/build docs/build
man8

9
Makefile
View file

@ -22,7 +22,7 @@ SHARE_DIR = $(DESTDIR)$(PREFIX)/share
.PHONY: install test docs .PHONY: install test docs
install: install: man
@install -Dm755 scripts/snap_pac.py $(SHARE_DIR)/libalpm/scripts/snap-pac @install -Dm755 scripts/snap_pac.py $(SHARE_DIR)/libalpm/scripts/snap-pac
@install -Dm644 hooks/* -t $(SHARE_DIR)/libalpm/hooks/ @install -Dm644 hooks/* -t $(SHARE_DIR)/libalpm/hooks/
@install -Dm644 LICENSE -t $(SHARE_DIR)/licenses/$(PKGNAME)/ @install -Dm644 LICENSE -t $(SHARE_DIR)/licenses/$(PKGNAME)/
@ -33,7 +33,10 @@ install:
test: test:
@python -m pytest -v . @python -m pytest -v .
docs: man:
@sphinx-build -a docs/source docs/build
@cd docs && make man @cd docs && make man
@mkdir -p man8
@awk 'NR==33{print ".SH DESCRIPTION"}7' docs/build/man/snap-pac.8 > man8/snap-pac.8 @awk 'NR==33{print ".SH DESCRIPTION"}7' docs/build/man/snap-pac.8 > man8/snap-pac.8
docs: man
@sphinx-build -a docs/source docs/build

547
man8/snap-pac.8
View file

@ -1,547 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "SNAP-PAC" "8" "Mar 28, 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
When you run pacman, the snapper pre/post snapshots are created automatically. For a fuller example see examples\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sudo pacman \-S vim
resolving dependencies...
looking for conflicting packages...
Packages (1) vim\-8.2.2489\-1
Total Installed Size: 3.79 MiB
Net Upgrade Size: 0.00 MiB
:: Proceed with installation? [Y/n]
(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: 7394
:: Processing package changes...
(1/1) installing vim [############] 100%
:: Running post\-transaction hooks...
(1/4) Arming ConditionNeedsUpdate...
(2/4) Updating icon theme caches...
(3/4) Updating the desktop file MIME type cache...
(4/4) Performing snapper post snapshots for the following configurations...
==> root: 7395
.ft P
.fi
.UNINDENT
.UNINDENT
.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\&.
.SS Dependencies
.sp
\fBpython\fP, \fBpacman\fP, and \fBsnapper\fP are all required.
.SS Testing
.sp
For testing, \fBpytest\fP is required. To run the tests do:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make test
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Documentation
.sp
Typically, you will not need to build the documentation on your own and can simply
access it by visiting the \fI\%online documentation\fP or by accessing the manpage:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
man 8 snap\-pac
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To build the documentation, \fBsphinx\fP is required. To build the documentation you can
do:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make docs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The resulting html documentation will then be located at \fBdocs/build/index.html\fP\&.
Additionally, this generates the manpage which will be located under \fBman8\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 Examples
.sp
Turn off snapshots for \fBroot\fP configuration and turn on for \fBhome\fP configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root]
snapshot = False
[home]
snapshot = True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Set the snapper to add the userdata \fBimportant=yes\fP for every snapshot in the \fBroot\fP
configuration when a system upgrade is performed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root]
important_commands = ["pacman \-Syu"]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Set the snapper to add the userdata \fBimportant=yes\fP for every snapshot in the \fBroot\fP
configuration when a pacman transaction handles the packages \fBlinux\fP and \fBlinux\-lts\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root]
important_packages = ["linux", "linux\-lts"]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here\(aqs a fuller example, with several options set for different configurations. In this
case the \fBroot\fP configuration snapshot will have \fBimportant=yes\fP when \fBlinux\fP and
\fBlinux\-lts\fP packages are part of the transaction. Additionally when full system
upgrades are performed \fBroot\fP snapshots will be marked \fBimportant=yes\fP\&. Note that
you don\(aqt have to add \fBsnapshot = True\fP for the \fBroot\fP configuration since that is
the default.
.sp
This file also turns one snapshots for the \fBhome\fP snapper configuration and adds the
userdata \fBrequestid=42,user=arthur\fP to all snapshots for that configuration.
Additionally he post snapshot description is overridden.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root]
important_packages = ["linux", "linux\-lts"]
important_commands = ["pacman \-Syu"]
[home]
snapshot = True
userdata = ["requestid=42", "user=arthur"]
post_description = "pacman transaction post snapshot"
.ft P
.fi
.UNINDENT
.UNINDENT
.SH 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.
.