Mastering GrUB – Part 6 – Invoking Grub Commands

1. Invoking grub2-install

The program ‘grub2-install’ generates a GRUB core image using‘grub2-mkimage’ and installs it on your system.  You must specify the device name on which you want to install GRUB, like this:
    

grub2-install INSTALL_DEVICE

   The device name INSTALL_DEVICE is an OS device name or a GRUB device name.

   ‘grub2-install’ accepts the following options:

   ‘–help’    Print a summary of the command-line options and exit.
‘–version’    Print the version number of GRUB and exit.
‘–boot-directory=DIR’   Install GRUB images under the directory ‘DIR/grub/’ This option is useful when you want to install GRUB into a separate partition or a removable disk.  If this option is not specified then it defaults to ‘/boot’, so
    

grub2-install /dev/sda

     is equivalent to    

grub2-install –boot-directory=/boot/ /dev/sda

    

Here is an example in which you have a separate “boot” partition which is mounted on ‘/mnt/boot’:

          grub2-install –boot-directory=/mnt/boot /dev/sdb

‘–recheck’

     Recheck the device map, even if ‘/boot/grub2/device.map’ already
     exists.  You should use this option whenever you add/remove a disk
     into/from your computer.

‘–no-rs-codes’
By default on x86 BIOS systems, ‘grub2-install’ will use some extra     space in the bootloader embedding area for Reed-Solomon error-correcting codes.  This enables GRUB to still boot successfully if some blocks are corrupted.  The exact amount of protection offered is dependent on available space in the embedding area.  R sectors of redundancy can tolerate up to R/2 corrupted sectors.  This redundancy may be cumbersome if attempting to     cryptographically validate the contents of the bootloader embedding area, or in more modern systems with GPT-style partition tables where GRUB does not reside in any  unpartitioned space outside of the MBR. Disable the Reed-Solomon     codes with this option.

 

2. Invoking grub2-mkconfig

The program ‘grub2-mkconfig’ generates a configuration file for GRUB.

     grub2-mkconfig -o /boot/grub2/grub.cfg

‘grub2-mkconfig’ accepts the following options:

‘–help’

Print a summary of the command-line options and exit.

‘–version’

 Print the version number of GRUB and exit.

‘-o FILE’ |  ‘–output=FILE’

     Send the generated configuration file to FILE.  The default is to
     send it to standard output.

 

3. Invoking grub2-mkpasswd-pbkdf2

The program ‘grub2-mkpasswd-pbkdf2’ generates password hashes for GRUB .

    grub2-mkpasswd-pbkdf2

‘grub2-mkpasswd-pbkdf2’ accepts the following options:

‘-c NUMBER’ | ‘–iteration-count=NUMBER’    Number of iterations of the underlying pseudo-random function. Defaults to 10000.

‘-l NUMBER’ | ‘–buflen=NUMBER’  Length of the generated hash.  Defaults to 64.

‘-s NUMBER’ | ‘–salt=NUMBER’    Length of the salt.  Defaults to 64.

 

4.  Invoking grub2-mkrelpath

The program ‘grub2-mkrelpath’ makes a file system path relative to the root of its containing file system.  For instance, if ‘/usr’ is a mount point, then:

     $ grub2-mkrelpath /usr/share/grub/unicode.pf2 ‘/share/grub/unicode.pf2’

This is mainly used internally by other GRUB utilities such as ‘grub2-mkconfig’ (*note Invoking grub2-mkconfig::), but may occasionally also be useful for debugging.

   ‘grub2-mkrelpath’ accepts the following options:

‘–help’      Print a summary of the command-line options and exit.

‘–version’   Print the version number of GRUB and exit.

5. Invoking grub2-mkrescue

The program ‘grub2-mkrescue’ generates a bootable GRUB rescue image.

     grub2-mkrescue -o grub.iso

All arguments not explicitly listed as ‘grub2-mkrescue’ options are passed on directly to ‘xorriso’ in ‘mkisofs’ emulation mode.  Options passed to ‘xorriso’ will normally be interpreted as ‘mkisofs’ options;
if the option ‘–‘ is used, then anything after that will be interpreted as native ‘xorriso’ options.

Non-option arguments specify additional source directories.  This is commonly used to add extra files to the image:

     mkdir -p disk/boot/grub  
     (add extra files to ‘disk/boot/grub’)
     grub2-mkrescue -o grub.iso disk

   

‘grub2-mkrescue’ accepts the following options:

    ‘–help’
     Print a summary of the command-line options and exit.

    ‘–version’
     Print the version number of GRUB and exit.

    ‘-o FILE’ | ‘–output=FILE’
     Save output in FILE.  This “option” is required.

     ‘–modules=MODULES’
     Pre-load the named GRUB modules in the image.  Multiple entries in MODULES should be separated by whitespace (so you will probably need to quote this for your shell).

‘–rom-directory=DIR’
     If generating images for the QEMU or Coreboot platforms, copy the
     resulting ‘qemu.img’ or ‘coreboot.elf’ files respectively to the
     DIR directory as well as including them in the image.

‘–xorriso=FILE’
     Use FILE as the ‘xorriso’ program, rather than the built-in
     default.

‘–grub-mkimage=FILE’
     Use FILE as the ‘grub2-mkimage’ program, rather than the built-in
     default.

6. Invoking grub2-mount

The program ‘grub2-mount’ performs a read-only mount of any file system or file system image that GRUB understands, using GRUB’s file system drivers via FUSE. (It is only available if FUSE development files were present when GRUB was built.)  This has a number of uses:

It provides a convenient way to check how GRUB will view a file      system at boot time.  You can use normal command-line tools to  compare that view with that of your operating system, making it easy to find bugs.

It offers true read-only mounts.  Linux does not have these for journalling file systems, because it will always attempt to replay the journal at mount time; while you can temporarily mark the block device read-only to avoid this, that causes the mount to fail. Since GRUB intentionally contains no code for writing to file systems, it can easily provide a guaranteed read-only mount     mechanism.

It allows you to examine any file system that GRUB understands without needing to load additional modules into your running kernel, which may be useful in constrained environments such as installers.

Since it can examine file system images (contained in regular files) just as easily as file systems on block devices, you can use it to inspect any file system image that GRUB understands with only enough privileges to use FUSE, even if nobody has yet written a FUSE module specifically for that file system type.

Using ‘grub2-mount’ is normally as simple as:

     grub2-mount /dev/sda1 /mnt

‘grub2-mount’ must be given one or more images and a mount point as non-option arguments (if it is given more than one image, it will treat them as a RAID set), and also accepts the following options:

‘–help’
     Print a summary of the command-line options and exit.

‘–version’
     Print the version number of GRUB and exit.

‘-C’ | ‘–crypto’
     Mount encrypted devices, prompting for a passphrase if necessary.

‘-d STRING’ | ‘–debug=STRING’
     Show debugging output for conditions matching STRING.

‘-K prompt|FILE’ | ‘–zfs-key=prompt|FILE’
     Load a ZFS encryption key.  If you use ‘prompt’ as the argument,      ‘grub2-mount’ will read a passphrase from the terminal; otherwise, it will read key material from the specified file.

‘-r DEVICE’ | ‘–root=DEVICE’
     Set the GRUB root device to DEVICE.  You do not normally need to
     set this; ‘grub2-mount’ will automatically set the root device to
     the root of the supplied file system.

     If DEVICE is just a number, then it will be treated as a partition
     number within the supplied image.  This means that, if you have an
     image of an entire disk in ‘disk.img’, then you can use this
     command to mount its second partition:

          grub2-mount -r 2 disk.img mount-point

‘-v’ | ‘–verbose’
     Print verbose messages.

7. Invoking grub2-probe

The program ‘grub2-probe’ probes device information for a given path or
device.

     grub2-probe –target=fs /boot/grub
     grub2-probe –target=drive –device /dev/sda1

   ‘grub2-probe’ must be given a path or device as a non-option argument,
and also accepts the following options:

‘–help’
     Print a summary of the command-line options and exit.

‘–version’
     Print the version number of GRUB and exit.

‘-d’ | ‘–device’
     If this option is given, then the non-option argument is a system
     device name (such as ‘/dev/sda1’), and ‘grub2-probe’ will print
     information about that device.  If it is not given, then the
     non-option argument is a filesystem path (such as ‘/boot/grub’),
     and ‘grub2-probe’ will print information about the device containing
     that part of the filesystem.

‘-m FILE’ | ‘–device-map=FILE’
     Use FILE as the device map (*note Device map::) rather than the
     default, usually ‘/boot/grub2/device.map’.

‘-t TARGET’ | ‘–target=TARGET’
     Print information about the given path or device as defined by
     TARGET.  The available targets and their meanings are:

     ‘fs’
          GRUB filesystem module.
     ‘fs_uuid’
          Filesystem Universally Unique Identifier (UUID).
     ‘fs_label’
          Filesystem label.
     ‘drive’
          GRUB device name.
     ‘device’
          System device name.
     ‘partmap’
          GRUB partition map module.
     ‘abstraction’
          GRUB abstraction module (e.g.  ‘lvm’).
     ‘cryptodisk_uuid’
          Crypto device UUID.
     ‘msdos_parttype’
          MBR partition type code (two hexadecimal digits).
     ‘hints_string’
          A string of platform search hints suitable for passing to the
          ‘search’ command (*note search::).
     ‘bios_hints’
          Search hints for the PC BIOS platform.
     ‘ieee1275_hints’
          Search hints for the IEEE1275 platform.
     ‘baremetal_hints’
          Search hints for platforms where disks are addressed directly
          rather than via firmware.
     ‘efi_hints’
          Search hints for the EFI platform.
     ‘arc_hints’
          Search hints for the ARC platform.
     ‘compatibility_hint’
          A guess at a reasonable GRUB drive name for this device, which
          may be used as a fallback if the ‘search’ command fails.
     ‘disk’
          System device name for the whole disk.

‘-v’ | ‘–verbose’
     Print verbose messages.

8. Invoking grub2-script-check

The program ‘grub2-script-check’ takes a GRUB script file and checks it for syntax errors, similar to commands such as ‘sh -n’.  It may take a PATH as a non-option argument; if none is supplied, it will read from standard input.

     grub2-script-check /boot/grub2/grub.cfg

   ‘grub2-script-check’ accepts the following options:

‘–help’
     Print a summary of the command-line options and exit.

‘–version’
     Print the version number of GRUB and exit.

‘-v’ |‘–verbose’
     Print each line of input after reading it.