diff --git a/41_snapshots-btrfs b/41_snapshots-btrfs index 5bd25da..de52ea1 100755 --- a/41_snapshots-btrfs +++ b/41_snapshots-btrfs @@ -617,5 +617,5 @@ fi fi # warn when this script is run but there is no entry in grub.cfg -grep "snapshots-btrfs" "${grub_directory}/grub.cfg" || printf "\nWARNING: '%s' needs to run at least once to generate the snapshots (sub)menu entry in grub the main menu. \ +grep "snapshots-btrfs" "${grub_directory}/grub.cfg" >/dev/null 2>&1 || printf "\nWARNING: '%s' needs to run at least once to generate the snapshots (sub)menu entry in grub the main menu. \ After that this script can run alone to generate the snapshot entries.\n\n" "${GRUB_BTRFS_MKCONFIG:-grub-mkconfig}" >&2 ; diff --git a/config b/config index 0f5b1fd..ea5e051 100644 --- a/config +++ b/config @@ -1,7 +1,7 @@ #!/usr/bin/env bash -GRUB_BTRFS_VERSION=4.12-master-2023-04-05T16:05:29+00:00 +GRUB_BTRFS_VERSION=4.12-master-2023-04-28T16:26:00+00:00 # Disable grub-btrfs. # Default: "false" diff --git a/temp/grub-btrfs.8 b/temp/grub-btrfs.8 new file mode 100644 index 0000000..2e4892a --- /dev/null +++ b/temp/grub-btrfs.8 @@ -0,0 +1,280 @@ +.TH "grub-btrfs" "8" + +.SH "NAME" +.PP +grub-btrfs - Automatically add btrfs-Snapshots as a Grub submenu + +.SH "SYNOPSIS" +.PP +\fC/etc/grub.d/41_snapshots\-btrfs [\-V, \-\-version]\fP + +.SH "DESCRIPTION" +.PP +Improves grub by adding “btrfs snapshots” to the grub menu. + +.PP +You can boot your system on a “snapshot” from the grub menu. +Supports manual snapshots, snapper and timeshift. +Features of grub-btrfs: +.IP \(em 4 +Automatically list snapshots existing on root partition (btrfs). +.IP \(em 4 +Automatically detect if /boot is in separate partition. +.IP \(em 4 +Automatically detect kernel, initramfs and intel/amd microcode in /boot directory on snapshots. +.IP \(em 4 +Automatically create corresponding “menuentry” in grub.cfg +.IP \(em 4 +Automatically detect the type/tags and descriptions/comments of snapper/timeshift snapshots. +.IP \(em 4 +Automatically generate grub.cfg if you use the provided systemd service. + +.SH "CONFIGURATION" +.PP +grub-btrfs is configured via the file \fC/etc/default/grub\-btrfs/config\fP. +Possible options are: + +.SS "GENERAL" +.SS "\fCGRUB_BTRFS_DISABLE\fP" +.PP +Disable grub-btrfs if true. +.IP \(em 4 +Default: “false” +.IP \(em 4 +Example: \fCGRUB_BTRFS_DISABLE="true"\fP + +.SS "\fCGRUB_BTRFS_TITLE_FORMAT\fP" +.PP +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”) +.IP \(em 4 +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” +.IP \(em 4 +Example: \fCGRUB_BTRFS_LIMIT="50"\fP + +.SS "\fCGRUB_BTRFS_SUBVOLUME_SORT\fP" +.PP +Sort the found subvolumes by “ogeneration” or “generation” or “path” or “rootid”. +.IP \(em 4 +See Sorting section in +.BR btrfs-subvolume (8) +.PP +“-rootid” means list snapshot by new ones first. +.IP \(em 4 +Default: “-rootid” +.IP \(em 4 +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” +.IP \(em 4 +Example: \fCGRUB_BTRFS_SHOW_SNAPSHOTS_FOUND="false"\fP + +.SS "\fCGRUB_BTRFS_ROOTFLAGS\fP" +.PP +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 +takes priority over `fstab` entries. +NB: Do NOT include “subvol=...” or “subvolid=...” here. +.IP \(em 4 +Default: “” +.IP \(em 4 +Example: \fCGRUB_BTRFS_ROOTFLAGS="space_cache,commit=10,norecovery"\fP + +.SS "\fCGRUB_BTRFS_OVERRIDE_BOOT_PARTITION_DETECTION\fP" +.PP +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. +.IP \(em 4 +Default: “false” +.IP \(em 4 +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" +.PP +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. +.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 +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. +.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" +.PP +Ignore specific path during run “grub-mkconfig”. +Only exact paths are ignored. +e.g : if `specific path` = @, only `@` snapshot will be ignored. +.IP \(em 4 +Default: (“@”) +.IP \(em 4 +Example: \fCGRUB_BTRFS_IGNORE_SPECIFIC_PATH=("@home")\fP + +.SS "\fCGRUB_BTRFS_IGNORE_PREFIX_PATH\fP" +.PP +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. +.IP \(em 4 +Default: (“var/lib/docker” “@var/lib/docker” “@/var/lib/docker”) +.IP \(em 4 +Example: \fCGRUB_BTRFS_IGNORE_PREFIX_PATH=("var/lib/docker" "@var/lib/docker" "@/var/lib/docker")\fP + +.SS "\fCGRUB_BTRFS_IGNORE_SNAPSHOT_TYPE\fP" +.PP +Ignore specific type/tag of snapshot during run “grub-mkconfig”. +For snapper: +Type = single, pre, post. +For Timeshift: +Tag = boot, ondemand, hourly, daily, weekly, monthly. +.IP \(em 4 +Default: (“”) +.IP \(em 4 +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: (“”) +.IP \(em 4 +Example: \fCGRUB_BTRFS_IGNORE_SNAPSHOT_DESCRIPTION=("timeline")\fP + +.SS "DISTRIBUTION DEPENDENT SETTINGS" +.SS "\fCGRUB_BTRFS_BOOT_DIRNAME\fP" +.PP +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” +.IP \(em 4 +Example: \fCGRUB_BTRFS_BOOT_DIRNAME="/"\fP + +.SS "\fCGRUB_BTRFS_GRUB_DIRNAME\fP" +.PP +Location of the folder containing the “grub.cfg” file. +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 +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 +Name/path of the command to generate the grub menu, used by “grub-btrfs.service” +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. +.IP \(em 4 +Default: grub-mkconfig +.IP \(em 4 +Example: \fCGRUB_BTRFS_MKCONFIG=/sbin/grub2\-mkconfig\fP + +.SS "\fCGRUB_BTRFS_SCRIPT_CHECK\fP" +.PP +Name of grub-script-check command, used by “grub-btrfs” +Might be ’grub2-script-check’ on some systems (e.g. Fedora) +.IP \(em 4 +Default: grub-script-check +.IP \(em 4 +Example: \fCGRUB_BTRFS_SCRIPT_CHECK=grub2\-script\-check\fP + +.SS "\fCGRUB_BTRFS_MKCONFIG_LIB\fP" +.PP +Path of grub-mkconfig\d\s-2lib\s+2\u file, used by “grub-btrfs” +Might be ’/usr/share/grub2/grub-mkconfig\d\s-2lib\s+2\u’ on some systems (e.g. Opensuse) +.IP \(em 4 +Default: /usr/share/grub/grub-mkconfig\d\s-2lib\s+2\u +.IP \(em 4 +Example: \fCGRUB_BTRFS_MKCONFIG_LIB=/usr/share/grub2/grub\-mkconfig_lib\fP + +.SS "SECURITY" +.SS "\fCGRUB_BTRFS_PROTECTION_AUTHORIZED_USERS\fP" +.PP +Password protection management for submenu, snapshots +Refer to the Grub documentation \fIhttps://www.gnu.org/software/grub/manual/grub/grub.html#Authentication-and-authorisation\fP +and this comment \fIhttps://github.com/Antynea/grub-btrfs/issues/95#issuecomment-682295660\fP +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: “” +.IP \(em 4 +Example: \fCGRUB_BTRFS_PROTECTION_AUTHORIZED_USERS="userfoo,userbar"\fP + +.SS "\fCGRUB_BTRFS_DISABLE_PROTECTION_SUBMENU\fP" +.PP +Disable authentication support for submenu of Grub-btrfs only (--unrestricted) +does not work if GRUB\d\s-2BTRFS\s+2\u\d\s-2PROTECTION\s+2\u\d\s-2AUTHORIZED\s+2\u\d\s-2USERS\s+2\u is not empty +.IP \(em 4 +Default: “false” +.IP \(em 4 +Example: \fCGRUB_BTRFS_DISABLE_PROTECTION_SUBMENU="true"\fP + +.SH "FILES" +.PP +/etc/default/grub-btrfs/config + +.SH "SEE ALSO" +.IR btrfs (8) +.IR btrfs-subvolume (8) +.IR grub-btrfsd (8) +.IR grub-mkconfig (8) + +.SH "COPYRIGHT" +.PP +Copyright (c) 2022 Pascal Jäger diff --git a/temp/grub-btrfsd.8 b/temp/grub-btrfsd.8 new file mode 100644 index 0000000..5a2c016 --- /dev/null +++ b/temp/grub-btrfsd.8 @@ -0,0 +1,84 @@ +.TH "grub-btrfsd" "8" + +.SH "NAME" +.PP +grub-btrfsd - An OpenRC daemon to automatically update the grub menu with +.BR grub-btrfs (8) +.PP +when a new btrfs snapshot is created. + +.SH "SYNOPSIS" +.PP +\fCgrub\-btrfsd [\-h, \-\-help] [\-c, \-\-no\-color] [\-l, \-\-log\-file LOG_FILE] [\-r, \-\-recursive] [\-s, \-\-syslog] [\-t, \-\-timeshift\-auto] [\-o, \-\-timeshift\-old] [\-v, \-\-verbose] SNAPSHOTS_DIRS\fP + +.SH "DESCRIPTION" +.PP +Grub-btrfsd is a shell script which is meant to be run as a daemon. +Grub-btrfsd watches a directory where btrfs-snapshots are created or deleted via inotifywait and runs grub-mkconfig (if grub-mkconfig never ran before since grub-btrfs was installed) or \fC/etc/grub.d/41_snapshots\-btrfs\fP (when grub-mkconfig ran before with grub-btrfs installed) when something in that directory changes. + +.SH "OPTIONS" +.SS "\fCSNAPSHOTS_DIRS\fP" +.PP +This argument specifies the (space separated) paths where grub-btrfsd looks for newly created snapshots and snapshot deletions. It is usually defined by the program used to make snapshots. +E.g. for Snapper this would be \fC/.snapshots\fP. It is possible to define more than one directory here, all directories will inherit the same settings (recursive etc.). +This argument is not necessary to provide if \fC\-\-timeshift\-auto\fP is set. + +.SS "\fC\-c / \-\-no\-color\fP" +.PP +Disable colors in output. + +.SS "\fC\-l / \-\-log\-file\fP" +.PP +This arguments specifies a file where grub-btrfsd should write log messages. + +.SS "\fC\-r / \-\-recursive\fP" +.PP +Watch snapshot directory recursively + +.SS "\fC\-s / \-\-syslog\fP" +.PP +Write to syslog + +.SS "\fC\-t / \-\-timeshift\-auto\fP" +.PP +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 \fC/run/timeshift/$PID/backup/timeshift\-btrfs\fP. Where \fC$PID\fP 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 \fCSNAPSHOTS_DIRS\fP has no effect. + +.SS "\fC\-o / \-\-timeshift\-old\fP" +.PP +Look for snapshots in \fC/run/timeshift/backup/timeshift\-btrfs\fP instead of \fC/run/timeshift/$PID/backup/timeshift\-btrfs\fP. This is to be used for Timeshift versions <22.06. + +.SS "\fC\-v / \-\-verbose\fP" +.PP +Let the log of the daemon be more verbose + +.SS "\fC\-h / \-\-help\fP" +.PP +Displays a short help message. + +.SH "CONFIGURATION" +.PP +The daemon is usually configured via the file \fC/etc/conf.d/grub\-btrfsd\fP on openrc-init systems and \fCsudo systemctl edit \-\-full grub\-btrfsd\fP on systemd systems. In this file the arguments (See OPTIONS), that OpenRC passes to the daemon when it is started, can be configured. + +.SS "NOTES" +.PP +A common configuration for Snapper would be to set \fCSNAPSHOTS_DIR\fP to \fC/.snapshots\fP and not to set \fC\-\-timeshift\-auto\fP. +For Timeshift \fC\-\-timeshift\-auto\fP is set to true and \fCSNAPSHOTS_DIR\fP can be left as is. + +.SH "FILES" +.PP +\fC/etc/conf.d/grub\-btrfsd\fP +\fC/usr/lib/systemd/system/grub\-btrfsd.service\fP + +.SH "SEE ALSO" +.IR btrfs (8) +.IR btrfs-subvolume (8) +.IR grub-btrfsd (8) +.IR grub-mkconfig (8) +.IR inotifywait (1) +.IR openrc (8) +.IR rc-service (8) +.IR timeshift (1) + +.SH "COPYRIGHT" +.PP +Copyright (c) 2022 Pascal Jäger