grub-btrfs/manpages/grub-btrfs.8.org

grub-btrfs

• NAME
• SYNOPSIS
• DESCRIPTION
• CONFIGURATION
  • GENERAL
    • GRUB_BTRFS_DISABLE
    • GRUB_BTRFS_TITLE_FORMAT
    • GRUB_BTRFS_LIMIT
    • GRUB_BTRFS_SUBVOLUME_SORT
    • GRUB_BTRFS_SHOW_SNAPSHOTS_FOUND
    • GRUB_BTRFS_ROOTFLAGS
    • GRUB_BTRFS_OVERRIDE_BOOT_PARTITION_DETECTION
  • CUSTOM KERNELS
    • GRUB_BTRFS_NKERNEL / GRUB_BTRFS_NINIT / GRUB_BTRFS_CUSTOM_MICROCODE
  • SNAPSHOT FILTERING
    • GRUB_BTRFS_IGNORE_SPECIFIC_PATH
    • GRUB_BTRFS_IGNORE_PREFIX_PATH
    • GRUB_BTRFS_IGNORE_SNAPSHOT_TYPE
    • GRUB_BTRFS_IGNORE_SNAPSHOT_DESCRIPTION
  • DISTRIBUTION DEPENDENT SETTINGS
    • GRUB_BTRFS_BOOT_DIRNAME
    • GRUB_BTRFS_GRUB_DIRNAME
    • GRUB_BTRFS_MKCONFIG
    • GRUB_BTRFS_SCRIPT_CHECK
    • GRUB_BTRFS_MKCONFIG_LIB
  • SECURITY
    • GRUB_BTRFS_PROTECTION_AUTHORIZED_USERS
    • GRUB_BTRFS_DISABLE_PROTECTION_SUBMENU
• FILES
• SEE ALSO
• COPYRIGHT

NAME

grub-btrfs - Automatically add btrfs-Snapshots as a Grub submenu

SYNOPSIS

/etc/grub.d/41_snapshots-btrfs [-V, --version]

DESCRIPTION

Improves grub by adding "btrfs snapshots" to the grub menu.

You can boot your system on a "snapshot" from the grub menu. Supports manual snapshots, snapper and timeshift. Features of grub-btrfs:

• Automatically list snapshots existing on root partition (btrfs).
• Automatically detect if /boot is in separate partition.
• Automatically detect kernel, initramfs and intel/amd microcode in /boot directory on snapshots.
• Automatically create corresponding "menuentry" in grub.cfg
• Automatically detect the type/tags and descriptions/comments of snapper/timeshift snapshots.
• Automatically generate grub.cfg if you use the provided systemd service.

CONFIGURATION

grub-btrfs is configured via the file /etc/default/grub-btrfs/config. Possible options are:

GENERAL

GRUB_BTRFS_DISABLE

Disable grub-btrfs if true.

• Default: "false"
• Example: GRUB_BTRFS_DISABLE="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")

GRUB_BTRFS_LIMIT

Maximum number of snapshots in the GRUB snapshots sub menu.

• Default: "50"

-Example: GRUB_BTRFS_LIMIT="50"

GRUB_BTRFS_SUBVOLUME_SORT

Sort the found subvolumes by "ogeneration" or "generation" or "path" or "rootid".

• See Sorting section in

.BR btrfs-subvolume (8)

"-rootid" means list snapshot by new ones first.

• Default: "-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"

GRUB_BTRFS_ROOTFLAGS

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.

• Default: ""

-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"

CUSTOM KERNELS

GRUB_BTRFS_NKERNEL / GRUB_BTRFS_NINIT / GRUB_BTRFS_CUSTOM_MICROCODE

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

SNAPSHOT FILTERING

GRUB_BTRFS_IGNORE_SPECIFIC_PATH

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

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

GRUB_BTRFS_IGNORE_SNAPSHOT_TYPE

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.

• Default: ("")

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

DISTRIBUTION DEPENDENT SETTINGS

GRUB_BTRFS_BOOT_DIRNAME

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="/"

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"

GRUB_BTRFS_MKCONFIG

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.

• Default: grub-mkconfig

-Example: GRUB_BTRFS_MKCONFIG=/sbin/grub2-mkconfig

GRUB_BTRFS_SCRIPT_CHECK

Name of grub-script-check command, used by "grub-btrfs" Might be 'grub2-script-check' on some systems (e.g. Fedora)

• Default: grub-script-check
• Example: GRUB_BTRFS_SCRIPT_CHECK=grub2-script-check

GRUB_BTRFS_MKCONFIG_LIB

Path of grub-mkconfig_lib file, used by "grub-btrfs" Might be '/usr/share/grub2/grub-mkconfig_lib' on some systems (e.g. Opensuse)

• Default: /usr/share/grub/grub-mkconfig_lib
• Example: GRUB_BTRFS_MKCONFIG_LIB=/usr/share/grub2/grub-mkconfig_lib

SECURITY

GRUB_BTRFS_PROTECTION_AUTHORIZED_USERS

Password protection management for submenu, snapshots Refer to the Grub documentation https://www.gnu.org/software/grub/manual/grub/grub.html#Authentication-and-authorisation 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"

GRUB_BTRFS_DISABLE_PROTECTION_SUBMENU

Disable authentication support for submenu of Grub-btrfs only (–unrestricted) does not work if GRUB_BTRFS_PROTECTION_AUTHORIZED_USERS is not empty

• Default: "false"
• Example: GRUB_BTRFS_DISABLE_PROTECTION_SUBMENU="true"

FILES

/etc/default/grub-btrfs/config

SEE ALSO

.IR btrfs (8) .IR btrfs-subvolume (8) .IR grub-btrfsd (8) .IR grub-mkconfig (8)

COPYRIGHT

Copyright (c) 2022 Pascal Jäger