snap-pac/man8/snap-pac.8

'\" t
.TH SNAP-PAC 8 2017-02-04 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.

To undo changes from a pacman transaction, use \fIsnapper undochange\fR. See 
\fBsnapper\fR(8) and the following example.

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

\fBLINK_MODULES=\fR\fB\fIyes\fR\fR\fB or \fR\fB\fIno\fR\fR
.RS 4
When set to "yes" this, if the \fIlinux\fR package (or another package
specified by KERNEL_PACKAGE; see below) is updated, then a
symlink will be created in the kernel modules directory for the
currently running kernel to same directory in the pre snapshot of the
"root" configuration. This is so that the kernel modules will still be
available for use before a reboot is required. 

Default is "no".
.RE

\fBKERNEL_PACKAGE=\fR\fB\fIstring\fR\fR
.RS 4
Used to trigger module linking if LINK_MODULES is set to "yes".

Default is "linux".
.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
snapper algorithm used in cleaning up the pacman pre/post snapshots. See \fBsnapper\fR(8) for list of valid options.

Default is "number". 
.RE

\fBPRE_DESCRIPTION=\fR\fB\fIstring\fR\fR
.RS 4
snapper description used for the pacman pre snapshot.

Default is the parent program (usually pacman) that called the snapshot script.  
.RE

\fBPOST_DESCRIPTION=\fR\fB\fIstring\fR\fR
.RS 4
snapper description used for the pacman post snapshot.

Default is the list of packages that were installed/upgraded/removed
during the transaction.
.RE

.SH EXAMPLE

Installing the nano package as normal:

.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.  Tip: this is also logged in pacman's log).

And here are the snapshots:

.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

What changed?

.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

I truncated the above output, but it continues. See the manpage for snapper to
see what each symbol means. You can also do snapper diff in the same way—I'll
spare you that one.

To undo the upgrade:

.EX

    # snapper -c root undochange 1033..1034
    create:0 modify:3 delete:100

.EE

And nano is now gone, 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 CONFIGURATION.

.SS After restoring snapshot from snap-pac, 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).

.SH FAQ
.SS Does snap-pac backup non-btrfs /boot partitions?
Nope. 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

.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)