grub-mkconfig Command Linux: Complete Guide to Generate GRUB Configuration Files

The grub-mkconfig command is an essential tool for Linux system administrators and users who need to manage their system’s boot configuration. This powerful utility automatically generates GRUB (Grand Unified Bootloader) configuration files by scanning your system for installed operating systems and kernel images.

What is grub-mkconfig?

grub-mkconfig is a shell script that creates the main GRUB configuration file (/boot/grub/grub.cfg) by executing various helper scripts located in /etc/grub.d/. Unlike manual editing of configuration files, this command ensures proper syntax and automatically detects system changes.

Command Syntax

grub-mkconfig [OPTIONS] [OUTPUT_FILE]

Basic Usage

# Generate configuration and display to stdout
sudo grub-mkconfig

# Generate and write to default location
sudo grub-mkconfig -o /boot/grub/grub.cfg

# Alternative command (on some distributions)
sudo update-grub

Command Options

How grub-mkconfig Works

The command operates by executing scripts in a specific order from the /etc/grub.d/ directory:

1. 00_header: Sets basic configuration parameters
2. 05_debian_theme: Configures theme settings (distribution-specific)
3. 10_linux: Detects Linux kernels in /boot
4. 20_linux_xen: Handles Xen hypervisor configurations
5. 30_os-prober: Detects other operating systems
6. 40_custom: Includes custom user entries
7. 41_custom: Additional custom configurations

Practical Examples

Example 1: Standard Configuration Generation

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

Sample Output:

Generating grub configuration file ...
Found linux image: /boot/vmlinuz-5.15.0-56-generic
Found initrd image: /boot/initrd.img-5.15.0-56-generic
Found linux image: /boot/vmlinuz-5.15.0-53-generic
Found initrd image: /boot/initrd.img-5.15.0-53-generic
Found Windows Boot Manager on /dev/sda1@/EFI/Microsoft/Boot/bootmgfw.efi
done

Example 2: Preview Configuration Without Writing

sudo grub-mkconfig | less

This allows you to review the generated configuration before applying it.

Example 3: Backup and Update

# Create backup of current configuration
sudo cp /boot/grub/grub.cfg /boot/grub/grub.cfg.backup

# Generate new configuration
sudo grub-mkconfig -o /boot/grub/grub.cfg

Configuration Files and Settings

Main Configuration File

The primary settings are controlled through /etc/default/grub:

# Default boot entry
GRUB_DEFAULT=0

# Boot timeout in seconds
GRUB_TIMEOUT=5

# Kernel command line parameters
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"

# Additional kernel parameters
GRUB_CMDLINE_LINUX=""

# Hide GRUB menu (set to true to hide)
GRUB_TIMEOUT_STYLE=menu

# Resolution for GRUB menu
GRUB_GFXMODE=640x480

Common Configuration Modifications

Change Default Boot Entry:

GRUB_DEFAULT="1>2"  # Boot second submenu, third entry

Set Custom Timeout:

GRUB_TIMEOUT=10  # Wait 10 seconds before auto-boot

Add Kernel Parameters:

GRUB_CMDLINE_LINUX="acpi=off noapic"

Troubleshooting Common Issues

Permission Denied Error

$ grub-mkconfig -o /boot/grub/grub.cfg
grub-mkconfig: error: cannot write to `/boot/grub/grub.cfg': Permission denied

Solution: Run with sudo privileges:

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

Missing Operating Systems

If other operating systems aren’t detected:

# Install os-prober
sudo apt install os-prober  # Ubuntu/Debian
sudo dnf install os-prober  # Fedora

# Enable os-prober in GRUB configuration
echo "GRUB_DISABLE_OS_PROBER=false" | sudo tee -a /etc/default/grub

# Regenerate configuration
sudo grub-mkconfig -o /boot/grub/grub.cfg

Kernel Not Detected

Verify kernel files exist:

ls -la /boot/vmlinuz*
ls -la /boot/initrd*

Advanced Usage Scenarios

Custom Menu Entries

Create custom entries in /etc/grub.d/40_custom:

#!/bin/sh
exec tail -n +3 $0

menuentry "Custom Linux Boot" {
    set root='hd0,msdos1'
    linux /boot/vmlinuz-custom root=/dev/sda1 ro quiet splash
    initrd /boot/initrd-custom
}

Automated Updates with Scripts

#!/bin/bash
# update-grub-config.sh

# Backup current configuration
sudo cp /boot/grub/grub.cfg /boot/grub/grub.cfg.$(date +%Y%m%d_%H%M%S)

# Update configuration
sudo grub-mkconfig -o /boot/grub/grub.cfg

# Verify update
echo "GRUB configuration updated successfully"
echo "Boot entries found:"
sudo grep "menuentry " /boot/grub/grub.cfg | head -5

Distribution-Specific Variations

Ubuntu/Debian Systems

sudo update-grub  # Shortcut for grub-mkconfig
sudo update-grub2  # On older systems

RHEL/CentOS/Fedora Systems

sudo grub2-mkconfig -o /boot/grub2/grub.cfg  # BIOS systems
sudo grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg  # UEFI systems

Arch Linux Systems

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

Best Practices and Security

Regular Maintenance

• Backup before changes: Always backup existing configuration
• Test configurations: Preview generated config before applying
• Monitor boot process: Verify system boots correctly after updates
• Clean old kernels: Remove unused kernels to keep menu manageable

Security Considerations

# Set password protection for GRUB menu editing
echo "set superusers="admin"" | sudo tee -a /etc/grub.d/40_custom
echo "password admin grub123" | sudo tee -a /etc/grub.d/40_custom

# Regenerate configuration
sudo grub-mkconfig -o /boot/grub/grub.cfg

Monitoring and Validation

Verify Configuration Syntax

# Check configuration file syntax
sudo grub-script-check /boot/grub/grub.cfg

# List all menu entries
sudo grep "menuentry " /boot/grub/grub.cfg

Debug Configuration Issues

# Enable verbose output
sudo GRUB_DISABLE_SUBMENU=y grub-mkconfig -o /boot/grub/grub.cfg

# Check for specific modules
sudo grep -i "insmod" /boot/grub/grub.cfg

Performance Optimization

Optimize GRUB performance by modifying /etc/default/grub:

# Reduce timeout for faster boot
GRUB_TIMEOUT=2

# Disable submenu for simpler navigation
GRUB_DISABLE_SUBMENU=y

# Hide GRUB menu for single OS systems
GRUB_TIMEOUT_STYLE=hidden
GRUB_TIMEOUT=0

Conclusion

The grub-mkconfig command is an indispensable tool for maintaining Linux boot configurations. By understanding its syntax, options, and best practices, system administrators can ensure reliable boot processes while accommodating system changes and updates. Regular use of this command, combined with proper backup procedures, helps maintain stable and secure boot environments across diverse Linux distributions.

Remember to always test configuration changes in safe environments before applying them to production systems, and maintain regular backups of working configurations to ensure system recovery capabilities.