Merge branch 'master' into improve-config

This does not work anymore, but it should be similar to the systemd
service file anyway, where things are just written in one line.

Signed-off-by: Pascal Jäger <pascal.jaeger@leimstift.de>

41_snapshots-btrfs

@@ -91,6 +91,10 @@ btrfs_subvolume_sort="--sort=${GRUB_BTRFS_SUBVOLUME_SORT:-"-rootid"}"
 grub_directory=${GRUB_BTRFS_GRUB_DIRNAME:-"/boot/grub"}
 ## Customize BOOT directory, where kernels/initrams/microcode is saved.
 boot_directory=${GRUB_BTRFS_BOOT_DIRNAME:-"/boot"}
+## Customize GRUB-BTRFS.cfg directory, where "grub-btrfs.cfg" file is saved
+grub_btrfs_directory=${GRUB_BTRFS_GBTRFS_DIRNAME:-${grub_directory}}
+## Customize directory where "grub-btrfs.cfg" file is searched for by grub
+grub_btrfs_search_directory=${GRUB_BTRFS_GBTRFS_SEARCH_DIRNAME:-"\${prefix}"}
 ## Password protection management for submenu
 # Protection support for submenu (--unrestricted)
 case "${GRUB_BTRFS_DISABLE_PROTECTION_SUBMENU,,}" in
@@ -117,7 +121,7 @@ boot_hs=$(${grub_probe} --device ${boot_device} --target="hints_string" 2>/dev/n
 boot_fs=$(${grub_probe} --device ${boot_device} --target="fs" 2>/dev/null) # Type filesystem of boot device
 
 ## Parameters passed to the kernel
-kernel_parameters="$GRUB_CMDLINE_LINUX $GRUB_CMDLINE_LINUX_DEFAULT"
+kernel_parameters="$GRUB_CMDLINE_LINUX $GRUB_CMDLINE_LINUX_DEFAULT $GRUB_BTRFS_SNAPSHOT_KERNEL_PARAMETERS"
 ## Mount point location
 grub_btrfs_mount_point=$(mktemp -dt grub-btrfs.XXXXXXXXXX)
 ## Class for theme
@@ -177,7 +181,7 @@ fi
 ## Create entry
 entry()
 {
-    echo "$@" >> "$grub_directory/grub-btrfs.new"
+    echo "$@" >> "$grub_btrfs_directory/grub-btrfs.new"
 }
 
 ## menu entries
@@ -494,7 +498,7 @@ header_menu()
             local lenght_title_column_right=$(((${#var}-lenght_title_column_left)+1)) #+1 is necessary for extra "|" character
             header_entry+=$(printf "%${lenght_title_column_left}s%${lenght_title_column_right}s" "${title_column[${GRUB_BTRFS_TITLE_FORMAT[$key],,}]}" "|") # Final "|" is for visuals only
         done
-    sed -i "1imenuentry '|${header_entry}' { echo }" "$grub_directory/grub-btrfs.new" # First "|" is for visuals only
+    sed -i "1imenuentry '|${header_entry}' { echo }" "$grub_btrfs_directory/grub-btrfs.new" # First "|" is for visuals only
 }
 
 ## List of kernels, initramfs and microcode in snapshots
@@ -561,11 +565,11 @@ boot_separate()
     IFS=$oldIFS
 }
 
-rm -f "$grub_directory/grub-btrfs.new"
+rm -f "$grub_btrfs_directory/grub-btrfs.new"
-> "$grub_directory/grub-btrfs.new" # Create a "grub-btrfs.new" file in "grub_directory"
+> "$grub_btrfs_directory/grub-btrfs.new" # Create a "grub-btrfs.new" file in "grub_btrfs_directory"
 # Create mount point then mounting
 [[ ! -d $grub_btrfs_mount_point ]] && mkdir -p "$grub_btrfs_mount_point"
-mount -o ro,subvolid=5 /dev/disk/by-uuid/"$root_uuid" "$grub_btrfs_mount_point/"
+mount -o ro,subvolid=5 /dev/disk/by-uuid/"$root_uuid" "$grub_btrfs_mount_point/" > /dev/null
 trap "unmount_grub_btrfs_mount_point" EXIT # unmounting mount point on EXIT signal
 count_warning_menuentries=0 # Count menuentries
 count_limit_snap=0 # Count snapshots
@@ -585,16 +589,16 @@ if [[ "${count_limit_snap}" = "0" || -z "${count_limit_snap}" ]]; then
 fi
 # Make a submenu in GRUB (grub.cfg) and move "grub-btrfs.new" to "grub-btrfs.cfg"
 header_menu
-if "${bindir}/${GRUB_BTRFS_SCRIPT_CHECK:-grub-script-check}" "$grub_directory/grub-btrfs.new"; then
+if "${bindir}/${GRUB_BTRFS_SCRIPT_CHECK:-grub-script-check}" "$grub_btrfs_directory/grub-btrfs.new"; then
-    cat "$grub_directory/grub-btrfs.new" > "$grub_directory/grub-btrfs.cfg"
+    cat "$grub_btrfs_directory/grub-btrfs.new" > "$grub_btrfs_directory/grub-btrfs.cfg"
-    rm -f "$grub_directory/grub-btrfs.new"
+    rm -f "$grub_btrfs_directory/grub-btrfs.new"
     cat << EOF
 submenu '${submenuname}' ${protection_authorized_users}${unrestricted_access_submenu}{
-    configfile "\${prefix}/grub-btrfs.cfg"
+    configfile "${grub_btrfs_search_directory}/grub-btrfs.cfg"
 }
 EOF
 else
-    print_error "Syntax errors were detected in generated ${grub_directory}/grub-btrfs.new file. Old grub-btrfs.cfg (if present) was not replaced."
+    print_error "Syntax errors were detected in generated ${grub_btrfs_directory}/grub-btrfs.new file. Old grub-btrfs.cfg (if present) was not replaced."
 fi
 
 # warn when this script is run but there is no entry in grub.cfg

README.md

@@ -104,6 +104,8 @@ Disable colors in output.
 * `-l / --log-file`
 This arguments specifies a file where grub-btrfsd should write log messages.
 * `-s / --syslog`
+* `-o / --timeshift-old`
+Look for snapshots in `/run/timeshift/backup/timeshift-btrfs` instead of `/run/timeshift/$PID/backup/timeshift-btrfs.` This is to be used for Timeshift versions <22.06.
 * `-t / --timeshift-auto`
 This is a flag to activate the auto detection of the path where Timeshift stores snapshots. Newer versions (>=22.06) of Timeshift mount their snapshots to `/run/timeshift/$PID/backup/timeshift-btrfs`. Where `$PID` is the process ID of the currently running Timeshift session. The PID is changing every time Timeshift is opened. grub-btrfsd can automatically take care of the detection of the correct PID and directory if this flag is set. In this case the argument `SNAPSHOTS_DIR` has no effect.
 * `-v / --verbose`
@@ -160,8 +162,6 @@ sudo systemctl enable grub-btrfsd
 ```
 
 ##### 💼 Snapshots not in `/.snapshots`
-NOTE: This works also for Timeshift versions < 22.06, the path to watch would be `/run/timeshift/backup/timeshift-btrfs/snapshots`.
-
 By default the daemon is watching the directory `/.snapshots`. If the daemon should watch a different directory, it can be edited with
 ```bash
 sudo systemctl edit --full grub-btrfsd 
@@ -184,10 +184,11 @@ EnvironmentFile=/etc/default/grub-btrfs/config
 # SNAPSHOTS_DIR         Snapshot directory to watch, without effect when --timeshift-auto
 # Optional arguments:
 # -t, --timeshift-auto  Automatically detect Timeshifts snapshot directory
+# -o, --timeshift-old   Activate for timeshift versions <22.06
 # -l, --log-file        Specify a logfile to write to
 # -v, --verbose         Let the log of the daemon be more verbose
 # -s, --syslog          Write to syslog
-ExecStart=/usr/bin/grub-btrfsd --syslog /path/to/your/snapshot/directory
+ExecStart=/usr/bin/grub-btrfsd --syslog /.snapshots
 
 [Install]
 WantedBy=multi-user.target
@@ -282,21 +283,19 @@ After editing, the file should look like this:
 # Distributed under the terms of the GNU General Public License v3
 
 ## Where to locate the root snapshots
-#snapshots="/.snapshots" # Snapper in the root directory
+snapshots="/.snapshots" # Snapper in the root directory
 #snapshots="/run/timeshift/backup/timeshift-btrfs/snapshots" # Timeshift < v22.06
-snapshots="/path/to/your/snapshot/directory"
 
 ## Optional arguments to run with the daemon
+# Append options to this like this:
+# optional_args="--syslog --timeshift-auto --verbose"
 # Possible options are:
 # -t, --timeshift-auto  Automatically detect Timeshifts snapshot directory for timeshift >= 22.06
+# -o, --timeshift-old   Look for snapshots in directory of Timeshift <v22.06 (requires --timeshift-auto)
 # -l, --log-file        Specify a logfile to write to
 # -v, --verbose         Let the log of the daemon be more verbose
 # -s, --syslog          Write to syslog
-# Uncomment the line to activate the option
+optional_args="--syslog"
-optional_args+="--syslog " # write to syslog by default
-#optional_args+="--timeshift-auto "
-#optional_args+="--log-file /var/log/grub-btrfsd.log "
-#optional_args+="--verbose "
 ```
 
 After that, the daemon should be restarted with
@@ -383,6 +382,23 @@ sudo /usr/bin/grub-btrfsd /.snapshots --verbose` (for snapper)
 Or pass `--verbose` to the daemon using the Systemd .service-file or the OpenRC conf.d file respectively. (see Daemon installation instructions how to do that)
 
 - - -
+### Development
+Grub-btrfs uses a rudimentary system of automatic versioning to tell apart different commits. This is helpful when users report problems and it is not immediately clear what version they are using. 
+We therefore have the following script in `.git/hooks/pre-commit`:
+
+``` bash
+#!/bin/sh
+
+echo "Doing pre commit hook with version bump"
+version="$(git describe --tags --abbrev=0)-$(git rev-parse --abbrev-ref HEAD)-$(date -u -Iseconds)"
+echo "New version is ${version}"
+sed -i "s/GRUB_BTRFS_VERSION=.*/GRUB_BTRFS_VERSION=${version}/" config
+git add config
+```
+
+This automatically sets the version in the `config`-file to `[lasttag]-[branch-name]-[current-date-in-UTC]`.
+In order to create a Tag we don't want to have this long version. In this case we set the version manually in `config` and commit with `git commit --no-verify`. This avoids running the hook. 
+
 ### Special thanks for assistance and contributions
 * [Maxim Baz](https://github.com/maximbaz)
 * [Schievel1](https://github.com/Antynea/grub-btrfs/discussions/173#discussioncomment-1438790)

config

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 
-GRUB_BTRFS_VERSION=4.12-fix-snap-dir-check-2022-11-26T14:06:44+00:00
+
+GRUB_BTRFS_VERSION=4.12-improve-config-2022-12-06T22:10:24+00:00
 
 # Disable grub-btrfs.
 # Default: "false"
@@ -48,6 +49,13 @@ GRUB_BTRFS_VERSION=4.12-fix-snap-dir-check-2022-11-26T14:06:44+00:00
 # Default: ("")
 #GRUB_BTRFS_CUSTOM_MICROCODE=("custom-ucode.img" "custom-uc.img "custom_ucode.cpio")
 
+# Additonal kernel command line parameters that should be passed to the kernel
+# when booting a snapshot.
+# For dracut based distros this could be useful to pass "rd.live.overlay.overlayfs=1"
+# or "rd.live.overlay.readonly=1" to the Kernel for booting snapshots read only.
+# Default: ""
+#GRUB_BTRFS_SNAPSHOT_KERNEL_PARAMETERS="rd.live.overlay.overlayfs=1"
+
 # Comma seperated mount options to be used when booting a snapshot.
 # They can be defined here as well as in the "/" line inside the respective snapshots'
 # "/etc/fstab" files.  Mount options found in both places are combined, and this variable
@@ -88,7 +96,6 @@ GRUB_BTRFS_IGNORE_PREFIX_PATH=("var/lib/docker" "@var/lib/docker" "@/var/lib/doc
 #GRUB_BTRFS_OVERRIDE_BOOT_PARTITION_DETECTION="true"
 
 # Location of the folder containing the "grub.cfg" file.
-# Use by grub-btrfs to save the file "grub-btrfs.cfg".
 # Might be grub2 on some systems.
 # For example, on Fedora with EFI : "/boot/efi/EFI/fedora"
 # Default: "/boot/grub"
@@ -99,6 +106,24 @@ GRUB_BTRFS_IGNORE_PREFIX_PATH=("var/lib/docker" "@var/lib/docker" "@/var/lib/doc
 # Default: "/boot"
 #GRUB_BTRFS_BOOT_DIRNAME="/boot"
 
+# Location where grub-btrfs.cfg should be saved.
+# Some distributions (like OpenSuSE) store those files at the snapshot directory
+# instead of boot. Be aware that this direcory must be available for grub during
+# startup of the system.
+# Default: $GRUB_BTRFS_GRUB_DIRNAME
+#GRUB_BTRFS_GBTRFS_DIRNAME="/boot/grub"
+
+# Location of the directory where Grub searches for the grub-btrfs.cfg file.
+# Some distributions (like OpenSuSE) store those file at the snapshot directory
+# instead of boot. Be aware that this direcory must be available for grub during
+# startup of the system.
+# Default: "\${prefix}" # This is a grub variable that resolves to where grub is
+# installed. (like /boot/grub, /boot/efi/grub)
+# NOTE: If variables of grub are used here (like ${prefix}) they need to be escaped
+# with `\` before the `$`
+#GRUB_BTRFS_GBTRFS_SEARCH_DIRNAME="\${prefix}"
+
+
 # Name/path of grub-mkconfig command, use by "grub-btrfs.service"
 # Might be 'grub2-mkconfig' on some systems (Fedora ...)
 # Default paths are /sbin:/bin:/usr/sbin:/usr/bin,

grub-btrfsd

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/usr/bin/env bash
 # Copyright 2022 Pascal Jaeger
 # Distributed under the terms of the GNU General Public License v3
 # Update GRUB when new BTRFS snapshots are created.
@@ -158,7 +158,7 @@ shift $(( OPTIND - 1 ))
 snapshots="${1}"
 
 # check if inotify exists, see issue #227
-if ! command -v inotifywait &> /dev/null; then
+if ! command -v inotifywait >/dev/null 2>&1; then
     err "[!] inotifywait was not found, exiting. Is inotify-tools installed?" "${RED}" >&2
     exit 1
 fi

grub-btrfsd.confd

@@ -6,13 +6,12 @@ snapshots="/.snapshots" # Snapper in the root directory
 #snapshots="/run/timeshift/backup/timeshift-btrfs/snapshots" # Timeshift < v22.06
 
 ## Optional arguments to run with the daemon
+# Append options to this like this:
+# optional_args="--syslog --timeshift-auto --verbose"
 # Possible options are:
 # -t, --timeshift-auto  Automatically detect Timeshifts snapshot directory for timeshift >= 22.06
+# -o, --timeshift-old   Look for snapshots in directory of Timeshift <v22.06 (requires --timeshift-auto)
 # -l, --log-file        Specify a logfile to write to
 # -v, --verbose         Let the log of the daemon be more verbose
 # -s, --syslog          Write to syslog
-# Uncomment the line to activate the option
+optional_args="--syslog"
-optional_args+="--syslog " # write to syslog by default
-#optional_args+="--timeshift-auto "
-#optional_args+="--log-file /var/log/grub-btrfsd.log "
-#optional_args+="--verbose "

grub-btrfsd.service

@@ -13,6 +13,7 @@ EnvironmentFile=/etc/default/grub-btrfs/config
 # SNAPSHOTS_DIR         Snapshot directory to watch, without effect when --timeshift-auto
 # Optional arguments:
 # -t, --timeshift-auto  Automatically detect Timeshifts snapshot directory
+# -o, --timeshift-old   Activate for timeshift versions <22.06
 # -l, --log-file        Specify a logfile to write to
 # -v, --verbose         Let the log of the daemon be more verbose
 # -s, --syslog          Write to syslog

initramfs/readme.md

@@ -39,7 +39,11 @@ You notice that the name of the `hook` must match the name of the 2 installed fi
 Re-generate your initramfs  
 `mkinitcpio -P` (option -P means, all preset present in `/etc/mkinitcpio.d`)
 
+#### Dracut based distros
+Distributions that use Dracut to make their initramfs (many of the Fedora based Distros) simply have to pass either `rd.live.overlay.readonly=1` (to boot into the snapshot read only) or `rd.live.overlay.overlayfs=1` (to act like a livedisk, that is files can be changed but changes will be lost on the next boot) to their kernel command line in grub. 
+Grub-btrfs provides the variable `GRUB_BTRFS_SNAPSHOT_KERNEL_PARAMETERS` to add any command to the kernel command line. Set it to `GRUB_BTRFS_SNAPSHOT_KERNEL_PARAMETERS="rd.live.overlay.overlayfs=1"` to make snapshots immutable when booted into. 
+After changing this run `sudo /etc/grub.d/41_snapshots-btrfs` to generate a new snapshot-submenu with the parameter added. 
+
 #### Other distribution
-Refer to your distribution's documentation  
+Refer to your distribution's documentation or contribute to this project to add a paragraph.
-or contribute to this project to add a paragraph.
 #

manpages/grub-btrfs.8.man

@@ -1,4 +1,4 @@
-.TH "grub-btrfs" "8"
+.TH "grub-btrfs" "8" 
 
 .SH "NAME"
 .PP
@@ -48,16 +48,16 @@ Example: \fCGRUB_BTRFS_DISABLE="true"\fP
 The snapshot entries submenu in Grub are added according to this line. It is possible to change to order of the fields.
 .IP \(em 4
 Default: (“date” “snapshot” “type” “description”)
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_TITLE_FORMAT=("date" "snapshot" "type" "description")\fP
+Example: \fCGRUB_BTRFS_TITLE_FORMAT=("date" "snapshot" "type" "description")\fP
 
 .SS "\fCGRUB_BTRFS_LIMIT\fP"
 .PP
 Maximum number of snapshots in the GRUB snapshots sub menu.
 .IP \(em 4
 Default: “50”
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_LIMIT="50"\fP
+Example: \fCGRUB_BTRFS_LIMIT="50"\fP
 
 .SS "\fCGRUB_BTRFS_SUBVOLUME_SORT\fP"
 .PP
@@ -69,16 +69,16 @@ See Sorting section in
 “-rootid” means list snapshot by new ones first.
 .IP \(em 4
 Default: “-rootid”
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_SUBVOLUME_SORT="+ogen,\-gen,path,rootid"\fP
+Example: \fCGRUB_BTRFS_SUBVOLUME_SORT="+ogen,\-gen,path,rootid"\fP
 
 .SS "\fCGRUB_BTRFS_SHOW_SNAPSHOTS_FOUND\fP"
 .PP
 Show snapshots found during run “grub-mkconfig”
 .IP \(em 4
 Default: “true”
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_SHOW_SNAPSHOTS_FOUND="false"\fP
+Example: \fCGRUB_BTRFS_SHOW_SNAPSHOTS_FOUND="false"\fP
 
 .SS "\fCGRUB_BTRFS_ROOTFLAGS\fP"
 .PP
@@ -89,8 +89,8 @@ takes priority over `fstab` entries.
 NB: Do NOT include “subvol=...” or “subvolid=...” here.
 .IP \(em 4
 Default: “”
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_ROOTFLAGS="space_cache,commit=10,norecovery"\fP
+Example: \fCGRUB_BTRFS_ROOTFLAGS="space_cache,commit=10,norecovery"\fP
 
 .SS "\fCGRUB_BTRFS_OVERRIDE_BOOT_PARTITION_DETECTION\fP"
 .PP
@@ -99,8 +99,8 @@ either located at the system root or on a separate partition or in a subvolume,
 Change to “true” if your boot partition is not detected as separate.
 .IP \(em 4
 Default: “false”
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_OVERRIDE_BOOT_PARTITION_DETECTION="true"\fP
+Example: \fCGRUB_BTRFS_OVERRIDE_BOOT_PARTITION_DETECTION="true"\fP
 
 .SS "CUSTOM KERNELS"
 .SS "\fCGRUB_BTRFS_NKERNEL\fP / \fCGRUB_BTRFS_NINIT\fP / \fCGRUB_BTRFS_CUSTOM_MICROCODE\fP"
@@ -109,10 +109,21 @@ By default, “grub-btrfs” automatically detects most existing kernels, initra
 Customs kernel, initramfs and microcodes that are not detected can be added in these variables.
 .IP \(em 4
 Default: (“”)
+.IP \(em 4
+Example: \fCGRUB_BTRFS_NKERNEL=("kernel\-5.19.4\-custom" "vmlinux\-5.19.4\-custom")\fP
+\fCGRUB_BTRFS_NINIT=("initramfs\-5.19.4\-custom.img" "initrd\-5.19.4\-custom.img" "otherinit\-5.19.4\-custom.gz")\fP
+\fCGRUB_BTRFS_CUSTOM_MICROCODE=("custom\-ucode.img" "custom\-uc.img "custom_ucode.cpio")\fP
+
+.SS "\fCGRUB_BTRFS_SNAPSHOT_KERNEL_PARAMETERS\fP"
 .PP
--Example: \fCGRUB_BTRFS_NKERNEL=("kernel\-5.19.4\-custom" "vmlinux\-5.19.4\-custom")\fP
+Additonal kernel command line parameters that should be passed to the kernelwhen
-          \fCGRUB_BTRFS_NINIT=("initramfs\-5.19.4\-custom.img" "initrd\-5.19.4\-custom.img" "otherinit\-5.19.4\-custom.gz")\fP
+booting a snapshot.
-          \fCGRUB_BTRFS_CUSTOM_MICROCODE=("custom\-ucode.img" "custom\-uc.img "custom_ucode.cpio")\fP
+For dracut based distros this could be useful to pass “rd.live.overlay.overlayfs=1”
+or “rd.live.overlay.readonly=1” to the Kernel for booting read only snapshots.
+.IP \(em 4
+Default: “”
+.IP \(em 4
+Example: \fCGRUB_BTRFS_SNAPSHOT_KERNEL_PARAMETERS="rd.live.overlay.overlayfs=1"\fP
 
 .SS "SNAPSHOT FILTERING"
 .SS "\fCGRUB_BTRFS_IGNORE_SPECIFIC_PATH\fP"
@@ -122,8 +133,8 @@ Only exact paths are ignored.
 e.g : if `specific path` = @, only `@` snapshot will be ignored.
 .IP \(em 4
 Default: (“@”)
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_IGNORE_SPECIFIC_PATH=("@home")\fP
+Example: \fCGRUB_BTRFS_IGNORE_SPECIFIC_PATH=("@home")\fP
 
 .SS "\fCGRUB_BTRFS_IGNORE_PREFIX_PATH\fP"
 .PP
@@ -132,8 +143,8 @@ Any path starting with the specified string will be ignored.
 e.g : if `prefix path` = @, all snapshots beginning with “@/...” will be ignored.
 .IP \(em 4
 Default: (“var/lib/docker” “@var/lib/docker” “@/var/lib/docker”)
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_IGNORE_PREFIX_PATH=("var/lib/docker" "@var/lib/docker" "@/var/lib/docker")\fP
+Example: \fCGRUB_BTRFS_IGNORE_PREFIX_PATH=("var/lib/docker" "@var/lib/docker" "@/var/lib/docker")\fP
 
 .SS "\fCGRUB_BTRFS_IGNORE_SNAPSHOT_TYPE\fP"
 .PP
@@ -144,16 +155,16 @@ For Timeshift:
 Tag = boot, ondemand, hourly, daily, weekly, monthly.
 .IP \(em 4
 Default: (“”)
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_IGNORE_SNAPSHOT_TYPE=("ondemand")\fP
+Example: \fCGRUB_BTRFS_IGNORE_SNAPSHOT_TYPE=("ondemand")\fP
 
 .SS "\fCGRUB_BTRFS_IGNORE_SNAPSHOT_DESCRIPTION\fP"
 .PP
 Ignore specific description of snapshot during run “grub-mkconfig”.
 .IP \(em 4
 Default: (“”)
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_IGNORE_SNAPSHOT_DESCRIPTION=("timeline")\fP
+Example: \fCGRUB_BTRFS_IGNORE_SNAPSHOT_DESCRIPTION=("timeline")\fP
 
 .SS "DISTRIBUTION DEPENDENT SETTINGS"
 .SS "\fCGRUB_BTRFS_BOOT_DIRNAME\fP"
@@ -162,19 +173,46 @@ Location of kernels/initramfs/microcode.
 Used by “grub-btrfs” to detect the boot partition and the location of kernels, initramfs and microcodes.
 .IP \(em 4
 Default: “/boot”
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_BOOT_DIRNAME="/"\fP
+Example: \fCGRUB_BTRFS_BOOT_DIRNAME="/"\fP
 
 .SS "\fCGRUB_BTRFS_GRUB_DIRNAME\fP"
 .PP
 Location of the folder containing the “grub.cfg” file.
-Used by grub-btrfs to save the file “grub-btrfs.cfg”.
 Might be grub2 on some systems.
 For example, on Fedora with EFI : “/boot/efi/EFI/fedora”
 .IP \(em 4
 Default: “/boot/grub”
+.IP \(em 4
+Example: \fCGRUB_BTRFS_GRUB_DIRNAME="/boot/grub2"\fP
+
+.SS "\fCGRUB_BTRFS_GBTRFS_DIRNAME\fP"
 .PP
--Example: \fCGRUB_BTRFS_GRUB_DIRNAME="/boot/grub2"\fP
+Location where grub-btrfs.cfg should be saved.
+Some distributions (like OpenSuSE) store those file at the snapshot directory
+instead of boot. Be aware that this direcory must be available for grub during
+startup of the system.
+.IP \(em 4
+Default: \fC$GRUB_BTRFS_GRUB_DIRNAME\fP
+.IP \(em 4
+Example: \fCGRUB_BTRFS_GBTRFS_DIRNAME="/.snapshots"\fP
+
+.SS "\fCGRUB_BTRFS_GBTRFS_SEARCH_DIRNAME\fP"
+.PP
+Location of the directory where Grub searches for the grub-btrfs.cfg file.
+Some distributions (like OpenSuSE) store those file at the snapshot directory
+instead of boot. Be aware that this direcory must be available for grub during
+startup of the system.
+.IP \(em 4
+Default: “\${prefix}” (This is a grub variable that resolves to where grub is
+.PP
+installed. (like /boot/grub, /boot/efi/grub))
+.IP \(em 4
+NOTE: If variables of grub are used here like ${prefix}, they need to be escaped
+.PP
+with `$\` before the `$`
+.IP \(em 4
+Example: \fCGRUB_BTRFS_GBTRFS_SEARCH_DIRNAME="\${prefix}"\fP
 
 .SS "\fCGRUB_BTRFS_MKCONFIG\fP"
 .PP
@@ -184,8 +222,8 @@ Default paths are /sbin:/bin:/usr/sbin:/usr/bin, if your path is missing, report
 You can use the name of the command only or full the path.
 .IP \(em 4
 Default: grub-mkconfig
-.PP
+.IP \(em 4
--Example: \fCGRUB_BTRFS_MKCONFIG=/sbin/grub2\-mkconfig\fP
+Example: \fCGRUB_BTRFS_MKCONFIG=/sbin/grub2\-mkconfig\fP
 
 .SS "\fCGRUB_BTRFS_SCRIPT_CHECK\fP"
 .PP
@@ -214,7 +252,9 @@ and this comment \fIhttps://github.com/Antynea/grub-btrfs/issues/95#issuecomment
 Add authorized usernames separate by comma (userfoo,userbar).
 When Grub’s password protection is enabled, the superuser is authorized by default, it is not necessary to add it
 .IP \(em 4
-Default: “- Example: \fCGRUB_BTRFS_PROTECTION_AUTHORIZED_USERS="userfoo,userbar"\fP
+Default: “”
+.IP \(em 4
+Example: \fCGRUB_BTRFS_PROTECTION_AUTHORIZED_USERS="userfoo,userbar"\fP
 
 .SS "\fCGRUB_BTRFS_DISABLE_PROTECTION_SUBMENU\fP"
 .PP

manpages/grub-btrfs.8.org

@@ -1,6 +1,6 @@
 #+title: grub-btrfs
 #+author: Pascal Jaeger
-#+man_class_option: :sectionid 8
+#+MAN_CLASS_OPTIONS: :section-id "8"
 
 * NAME
     grub-btrfs - Automatically add btrfs-Snapshots as a Grub submenu
@@ -35,12 +35,12 @@ Disable grub-btrfs if true.
 *** ~GRUB_BTRFS_TITLE_FORMAT~
 The snapshot entries submenu in Grub are added according to this line. It is possible to change to order of the fields.
 - Default: ("date" "snapshot" "type" "description")
--Example: ~GRUB_BTRFS_TITLE_FORMAT=("date" "snapshot" "type" "description")~
+- Example: ~GRUB_BTRFS_TITLE_FORMAT=("date" "snapshot" "type" "description")~
 
 *** ~GRUB_BTRFS_LIMIT~
 Maximum number of snapshots in the GRUB snapshots sub menu.
 - Default: "50"
--Example: ~GRUB_BTRFS_LIMIT="50"~
+- Example: ~GRUB_BTRFS_LIMIT="50"~
 
 *** ~GRUB_BTRFS_SUBVOLUME_SORT~
 Sort the found subvolumes by "ogeneration" or "generation" or "path" or "rootid".
@@ -50,12 +50,12 @@ Sort the found subvolumes by "ogeneration" or "generation" or "path" or "rootid"
 #+END_MAN
 "-rootid" means list snapshot by new ones first.
 - Default: "-rootid"
--Example: ~GRUB_BTRFS_SUBVOLUME_SORT="+ogen,-gen,path,rootid"~
+- Example: ~GRUB_BTRFS_SUBVOLUME_SORT="+ogen,-gen,path,rootid"~
 
 *** ~GRUB_BTRFS_SHOW_SNAPSHOTS_FOUND~
 Show snapshots found during run "grub-mkconfig"
 - Default: "true"
--Example: ~GRUB_BTRFS_SHOW_SNAPSHOTS_FOUND="false"~
+- Example: ~GRUB_BTRFS_SHOW_SNAPSHOTS_FOUND="false"~
 
 *** ~GRUB_BTRFS_ROOTFLAGS~
 Comma seperated mount options to be used when booting a snapshot.
@@ -64,14 +64,14 @@ They can be defined here as well as in the "/" line inside the respective snapsh
 takes priority over `fstab` entries.
 NB: Do NOT include "subvol=..." or "subvolid=..." here.
 - Default: ""
--Example: ~GRUB_BTRFS_ROOTFLAGS="space_cache,commit=10,norecovery"~
+- Example: ~GRUB_BTRFS_ROOTFLAGS="space_cache,commit=10,norecovery"~
 
 *** ~GRUB_BTRFS_OVERRIDE_BOOT_PARTITION_DETECTION~
 By default "grub-btrfs" automatically detects your boot partition,
 either located at the system root or on a separate partition or in a subvolume,
 Change to "true" if your boot partition is not detected as separate.
 - Default: "false"
--Example: ~GRUB_BTRFS_OVERRIDE_BOOT_PARTITION_DETECTION="true"~
+- Example: ~GRUB_BTRFS_OVERRIDE_BOOT_PARTITION_DETECTION="true"~
 
 ** CUSTOM KERNELS
 
@@ -79,10 +79,18 @@ Change to "true" if your boot partition is not detected as separate.
 By default, "grub-btrfs" automatically detects most existing kernels, initramfs and microcode.
 Customs kernel, initramfs and microcodes that are not detected can be added in these variables.
 - Default: ("")
--Example: ~GRUB_BTRFS_NKERNEL=("kernel-5.19.4-custom" "vmlinux-5.19.4-custom")~
+- Example: ~GRUB_BTRFS_NKERNEL=("kernel-5.19.4-custom" "vmlinux-5.19.4-custom")~
           ~GRUB_BTRFS_NINIT=("initramfs-5.19.4-custom.img" "initrd-5.19.4-custom.img" "otherinit-5.19.4-custom.gz")~
           ~GRUB_BTRFS_CUSTOM_MICROCODE=("custom-ucode.img" "custom-uc.img "custom_ucode.cpio")~
 
+*** ~GRUB_BTRFS_SNAPSHOT_KERNEL_PARAMETERS~
+Additonal kernel command line parameters that should be passed to the kernelwhen
+booting a snapshot.
+For dracut based distros this could be useful to pass "rd.live.overlay.overlayfs=1"
+or "rd.live.overlay.readonly=1" to the Kernel for booting read only snapshots.
+- Default: ""
+- Example: ~GRUB_BTRFS_SNAPSHOT_KERNEL_PARAMETERS="rd.live.overlay.overlayfs=1"~
+
 ** SNAPSHOT FILTERING
 
 *** ~GRUB_BTRFS_IGNORE_SPECIFIC_PATH~
@@ -90,14 +98,14 @@ Ignore specific path during run "grub-mkconfig".
 Only exact paths are ignored.
 e.g : if `specific path` = @, only `@` snapshot will be ignored.
 - Default: ("@")
--Example: ~GRUB_BTRFS_IGNORE_SPECIFIC_PATH=("@home")~
+- Example: ~GRUB_BTRFS_IGNORE_SPECIFIC_PATH=("@home")~
 
 *** ~GRUB_BTRFS_IGNORE_PREFIX_PATH~
 Ignore prefix path during run "grub-mkconfig".
 Any path starting with the specified string will be ignored.
 e.g : if `prefix path` = @, all snapshots beginning with "@/..." will be ignored.
 - Default: ("var/lib/docker" "@var/lib/docker" "@/var/lib/docker")
--Example: ~GRUB_BTRFS_IGNORE_PREFIX_PATH=("var/lib/docker" "@var/lib/docker" "@/var/lib/docker")~
+- Example: ~GRUB_BTRFS_IGNORE_PREFIX_PATH=("var/lib/docker" "@var/lib/docker" "@/var/lib/docker")~
 
 *** ~GRUB_BTRFS_IGNORE_SNAPSHOT_TYPE~
 Ignore specific type/tag of snapshot during run "grub-mkconfig".
@@ -106,12 +114,12 @@ Type = single, pre, post.
 For Timeshift:
 Tag = boot, ondemand, hourly, daily, weekly, monthly.
 - Default: ("")
--Example: ~GRUB_BTRFS_IGNORE_SNAPSHOT_TYPE=("ondemand")~
+- Example: ~GRUB_BTRFS_IGNORE_SNAPSHOT_TYPE=("ondemand")~
 
 *** ~GRUB_BTRFS_IGNORE_SNAPSHOT_DESCRIPTION~
 Ignore specific description of snapshot during run "grub-mkconfig".
 - Default: ("")
--Example: ~GRUB_BTRFS_IGNORE_SNAPSHOT_DESCRIPTION=("timeline")~
+- Example: ~GRUB_BTRFS_IGNORE_SNAPSHOT_DESCRIPTION=("timeline")~
 
 ** DISTRIBUTION DEPENDENT SETTINGS
 
@@ -119,23 +127,44 @@ Ignore specific description of snapshot during run "grub-mkconfig".
 Location of kernels/initramfs/microcode.
 Used by "grub-btrfs" to detect the boot partition and the location of kernels, initramfs and microcodes.
 - Default: "/boot"
--Example: ~GRUB_BTRFS_BOOT_DIRNAME="/"~
+- Example: ~GRUB_BTRFS_BOOT_DIRNAME="/"~
 
 *** ~GRUB_BTRFS_GRUB_DIRNAME~
 Location of the folder containing the "grub.cfg" file.
-Used by grub-btrfs to save the file "grub-btrfs.cfg".
 Might be grub2 on some systems.
 For example, on Fedora with EFI : "/boot/efi/EFI/fedora"
 - Default: "/boot/grub"
--Example: ~GRUB_BTRFS_GRUB_DIRNAME="/boot/grub2"~
+- Example: ~GRUB_BTRFS_GRUB_DIRNAME="/boot/grub2"~
+
+*** ~GRUB_BTRFS_GBTRFS_DIRNAME~
+ Location where grub-btrfs.cfg should be saved.
+ Some distributions (like OpenSuSE) store those file at the snapshot directory
+ instead of boot. Be aware that this direcory must be available for grub during
+ startup of the system.
+- Default: ~$GRUB_BTRFS_GRUB_DIRNAME~
+- Example: ~GRUB_BTRFS_GBTRFS_DIRNAME="/.snapshots"~
+
+*** ~GRUB_BTRFS_GBTRFS_SEARCH_DIRNAME~
+Location of the directory where Grub searches for the grub-btrfs.cfg file.
+Some distributions (like OpenSuSE) store those file at the snapshot directory
+instead of boot. Be aware that this direcory must be available for grub during
+startup of the system.
+- Default: "\${prefix}" (This is a grub variable that resolves to where grub is
+installed. (like /boot/grub, /boot/efi/grub))
+- NOTE: If variables of grub are used here like ${prefix}, they need to be escaped
+with `\` before the `$`
+- Example: ~GRUB_BTRFS_GBTRFS_SEARCH_DIRNAME="\${prefix}"~
 
 *** ~GRUB_BTRFS_MKCONFIG~
-Name/path of the command to generate the grub menu, used by "grub-btrfs.service"
+Name/path of the command to generate the grub menu, used by
+#+BEGIN_MAN
+.BR grub-btrfsd (8)
+#+END_MAN
 Might be 'grub2-mkconfig' on some systems (e.g. Fedora)
 Default paths are /sbin:/bin:/usr/sbin:/usr/bin, if your path is missing, report it on the upstream project.
 You can use the name of the command only or full the path.
 - Default: grub-mkconfig
--Example: ~GRUB_BTRFS_MKCONFIG=/sbin/grub2-mkconfig~
+- Example: ~GRUB_BTRFS_MKCONFIG=/sbin/grub2-mkconfig~
 
 *** ~GRUB_BTRFS_SCRIPT_CHECK~
 Name of grub-script-check command, used by "grub-btrfs"
@@ -157,7 +186,8 @@ Refer to the Grub documentation https://www.gnu.org/software/grub/manual/grub/gr
 and this comment https://github.com/Antynea/grub-btrfs/issues/95#issuecomment-682295660
 Add authorized usernames separate by comma (userfoo,userbar).
 When Grub's password protection is enabled, the superuser is authorized by default, it is not necessary to add it
-- Default: "- Example: ~GRUB_BTRFS_PROTECTION_AUTHORIZED_USERS="userfoo,userbar"~
+- Default: ""
+- Example: ~GRUB_BTRFS_PROTECTION_AUTHORIZED_USERS="userfoo,userbar"~
 
 *** ~GRUB_BTRFS_DISABLE_PROTECTION_SUBMENU~
 Disable authentication support for submenu of Grub-btrfs only (--unrestricted)

manpages/grub-btrfsd.8.man

@@ -1,4 +1,4 @@
-.TH "grub-btrfsd" "8"
+.TH "grub-btrfsd" "8" 
 
 .SH "NAME"
 .PP

manpages/grub-btrfsd.8.org

@@ -1,6 +1,6 @@
 #+title: grub-btrfsd
 #+author: Pascal Jaeger
-#+man_class_option: :sectionid 8
+#+MAN_CLASS_OPTIONS: :section-id "8"
 
 * NAME
 grub-btrfsd - An OpenRC daemon to automatically update the grub menu with