diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..31c52ac --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,28 @@ +name: Docs +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Install Python + uses: actions/setup-python@v1 + with: + python-version: 3.9 + - name: Install dependencies + run: python -m pip install --upgrade pip sphinx + - name: Build docs + run: cd docs && sphinx-build source build + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/build + publish_branch: gh-pages diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..64b1b2e --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,52 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'snap-pac' +copyright = '2021, Wes Barnett, PhD' +author = 'Wes Barnett, PhD' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 0000000..f177075 --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,34 @@ +Configuration +============= + +.. toctree:: + :maxdepth: 2 + +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 ``root`` snapper configuration is snapshotted. + +A commented example configuration files is located at ``/etc/snap-pac.ini.example``. + +To configure, copy the example configuration file: + +.. code-block:: bash + + cp /etc/snap-pac.ini{.example,} + +Then edit with your favorite editor. The file is commented and should be +self-explanatory. + +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. + +Environment Variables +--------------------- + +To temporarily prevent snapshots from being performed for a single pacman +command, set the environment variable ``SNAP_PAC_SKIP``. For example: + +.. code-block:: bash + + sudo SNAP_PAC_SKIP=y pacman -Syu diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 0000000..5877ed1 --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,92 @@ +Example +======= + +.. toctree:: + :maxdepth: 2 + +Here is an example of how the snapshots are created and how to rollback and pacman +transaction. Here the nano package is installed: + +.. code-block:: bash + + pacman -S nano + +.. code-block:: none + + 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 + +The snapper snapshot number is given for each snapper configuration that is used. This +is also logged in pacman's log. + +Here are the snapshots created before and after the pacman transaction: + +.. code-block:: bash + + snapper -c root list -t pre-post | tail -n 1 + +.. code-block:: none + + 1033 | 1034 | Fri 22 Apr 2016 01:54:13 PM CDT | Fri 22 Apr 2016 01:54:14 PM CDT | pacman -S nano | + +Here is what changed during the transaction: + +.. code-block:: bash + + snapper -c root status 1033..1034 + +.. code-block:: none + + +..... /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 + +The above output is truncated, but it continues. See the `snapper(8) +`_ to for what each symbol means. You can also +do ``snapper diff`` in the same way. + +Then, to undo the pacman transaction: + +.. code-block:: bash + + snapper -c root undochange 1033..1034 + +.. code-block:: none + + create:0 modify:3 delete:100 + +Now nano is no longer installed, along with all the files it changed: + +.. code-block:: bash + + pacman -Qi nano + +.. code-block:: none + + error: package 'nano' was not found diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000..c6f17e4 --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,42 @@ +FAQ +=== + +.. toctree:: + :maxdepth: 2 + +**Does snap-pac backup non-btrfs /boot partitions?** + +No, but you can add a hook that does it for you. It would be something like the following: + +.. code-block:: none + + [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 + + +**How do I link old kernel modules automatically when the kernel is upgraded?** + +This behavior is no longer a part of this package. Use a pacman hook like the following: + +.. code-block:: none + + [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 'END{print $1}')/snapshot/usr/lib/modules/$(uname -r) /usr/lib/modules/" diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..018ddb5 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,41 @@ +.. snap-pac documentation master file, created by + sphinx-quickstart on Thu Mar 11 19:49:12 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to snap-pac's documentation! +==================================== + +.. toctree:: + :maxdepth: 2 + + installation + configuration + examples + troubleshooting + faq + +This is a set of `pacman `_ hooks and script that causes +`snapper `_ 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, so that the user can easily find which changes he or she may want to +revert. + +To undo changes from a pacman transaction, use ``snapper undochange``. See the `snapper +documentation `_ for more details as well as +examples. + +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 /. 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. diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..345ab0a --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,30 @@ +Installation +============ + +Install the ``snap-pac`` package using pacman: + +.. code-block:: bash + + pacman -S snap-pac + +Alternatively download the `latest release and signature +`_. Then, verify the download: + +.. code-block:: bash + + gpg --verify snap-pac-.tar.gz.sig + +where ```` is the version number you downloaded. + +Finally, run: + +.. code-block:: bash + + make install + +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 +``F7B28C61944FE30DABEEB0B01070BCC98C18BD66``. + +For previous releases, the key's fingerprint was +``8535CEF3F3C38EE69555BF67E4B5E45AA3B8C5C3``. diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 0000000..be961c6 --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,23 @@ +Troubleshooting +=============== + +.. toctree:: + :maxdepth: 2 + +**snap-pac is only taking snapshots of the root configuration.** + +That's the default behavior. See :doc:`configuration`. + +**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 :doc:`configuration`. + +**After restoring snapshot from snap-pac, the 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). You can add the +database lock file to a snapper filter so that snapper won't consider it when +performing snapper diff, snapper status, snapper undochange, etc. See the Filters +section in `snapper(8) `_ for more information.