Diagnosing Boot Problems in Alpine Linux

Boot problems can be frustrating, but with systematic diagnosis, most issues can be resolved. Let’s learn how to identify and fix common boot problems in Alpine Linux! 🚀

Understanding Alpine Linux Boot Process

The boot sequence:

BIOS/UEFI: Hardware initialization
Bootloader: GRUB or syslinux loads
Kernel: Linux kernel initializes
initramfs: Initial RAM filesystem
Init System: OpenRC starts services
Login: System ready for use

Common Boot Problems

Typical issues include:

Bootloader failures: GRUB errors
Kernel panics: System crashes during boot
Missing initramfs: Can’t find boot files
File system errors: Corrupted partitions
Service failures: Critical services won’t start
Hardware issues: Disk or memory failures

Step 1: Initial Diagnosis

Boot to Recovery Mode

# At GRUB menu, press 'e' to edit
# Add to kernel line:
single init=/bin/sh

# Or boot with rescue media
# Download Alpine extended ISO
# Boot from USB/CD

Check Boot Messages

# During boot, remove 'quiet' parameter
# Press ESC to see messages

# After boot (if successful)
dmesg | less
dmesg | grep -i error
dmesg | grep -i fail

Step 2: Bootloader Issues

GRUB Problems

# Boot from rescue media
# Mount root partition
mount /dev/sda2 /mnt
mount /dev/sda1 /mnt/boot

# Chroot into system
mount --bind /dev /mnt/dev
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys
chroot /mnt

# Reinstall GRUB
grub-install /dev/sda
grub-mkconfig -o /boot/grub/grub.cfg

# Fix GRUB configuration
nano /etc/default/grub

Common GRUB fixes:

# /etc/default/grub
GRUB_DEFAULT=0
GRUB_TIMEOUT=5
GRUB_CMDLINE_LINUX_DEFAULT="quiet"
GRUB_CMDLINE_LINUX=""

# For troubleshooting
GRUB_CMDLINE_LINUX_DEFAULT=""
GRUB_TERMINAL=console

Syslinux Problems

# For syslinux systems
# Mount boot partition
mount /dev/sda1 /mnt

# Check syslinux configuration
cat /mnt/syslinux/syslinux.cfg

# Reinstall syslinux
syslinux --install /dev/sda1

# Update MBR
dd if=/usr/share/syslinux/mbr.bin of=/dev/sda bs=440 count=1

Step 3: Kernel and initramfs Issues

Regenerate initramfs

# Update initramfs
mkinitfs

# List available kernels
ls /lib/modules/

# Generate for specific kernel
mkinitfs -k 5.15.75-0-lts

# With specific features
mkinitfs -F "ata base ide scsi usb virtio ext4"

# Check initramfs contents
lsinitramfs /boot/initramfs-lts

Kernel Module Issues

# List loaded modules
lsmod

# Check module dependencies
modprobe --show-depends module_name

# Force load module
modprobe -f module_name

# Blacklist problematic module
echo "blacklist module_name" >> /etc/modprobe.d/blacklist.conf

Step 4: File System Problems

Check and Repair File Systems

# Boot from rescue media
# Check root filesystem
fsck -f /dev/sda2

# Force check on ext4
e2fsck -f /dev/sda2

# Check all filesystems
fsck -A

# For btrfs
btrfs check /dev/sda2
btrfs check --repair /dev/sda2

Mount Issues

# Check fstab for errors
cat /etc/fstab

# Test mount
mount -a

# Mount with specific options
mount -o ro,noload /dev/sda2 /mnt

# Check UUID
blkid
ls -l /dev/disk/by-uuid/

Step 5: Hardware Diagnostics

Memory Testing

# Install memtest86+
apk add memtest86+

# Add to GRUB
cat >> /etc/grub.d/20_memtest86+ << 'EOF'
#!/bin/sh
set -e
. /usr/share/grub/grub-mkconfig_lib
if [ -f /boot/memtest86+.bin ]; then
  MEMTEST86="/boot/memtest86+.bin"
  printf "menuentry \"Memory test (memtest86+)\" {\n"
  printf "\tlinux16 %s\n" "${MEMTEST86}"
  printf "}\n"
fi
EOF

chmod +x /etc/grub.d/20_memtest86+
grub-mkconfig -o /boot/grub/grub.cfg

Disk Health Check

# Install smartmontools
apk add smartmontools

# Check disk health
smartctl -H /dev/sda

# Run full test
smartctl -t long /dev/sda

# Check test results
smartctl -a /dev/sda

# Check for bad blocks
badblocks -v /dev/sda

Step 6: Boot Logging and Debugging

Enable Verbose Boot

# Remove quiet from kernel parameters
# Edit GRUB configuration
nano /etc/default/grub

# Change:
GRUB_CMDLINE_LINUX_DEFAULT=""

# Add debug options:
GRUB_CMDLINE_LINUX="debug initcall_debug"

# Update GRUB
grub-mkconfig -o /boot/grub/grub.cfg

Configure Boot Logging

# Enable bootlog service
rc-update add bootlog boot

# Configure console logging
echo "rc_logger=\"YES\"" >> /etc/rc.conf
echo "rc_log_path=\"/var/log/rc.log\"" >> /etc/rc.conf

# Enable kernel logging
echo "kern.*  /var/log/kernel.log" >> /etc/rsyslog.conf

Step 7: Service Boot Issues

Debug OpenRC Services

# Check service status
rc-status -a

# List failed services
rc-status -c

# Start service manually with debug
/etc/init.d/service_name start --debug

# Check service dependencies
rc-update -v show

# Reset service state
rm /run/openrc/started/service_name
rm /run/openrc/failed/service_name

Fix Common Service Issues

# Networking service failure
# Check network configuration
cat /etc/network/interfaces

# Start networking manually
ifup -a

# Database service failure
# Check permissions
ls -la /var/lib/mysql/
chown -R mysql:mysql /var/lib/mysql/

# Clear service cache
rm -rf /run/openrc/cache/*

Step 8: Recovery Procedures

Create Recovery Script

#!/bin/sh
# Alpine Linux Boot Recovery Script

echo "=== Alpine Linux Boot Recovery ==="
echo "1. Check filesystems"
echo "2. Rebuild initramfs"
echo "3. Reinstall bootloader"
echo "4. Fix network configuration"
echo "5. Reset root password"
echo "6. Exit"

read -p "Select option: " choice

case $choice in
    1)
        echo "Checking filesystems..."
        fsck -A -y
        ;;
    2)
        echo "Rebuilding initramfs..."
        mkinitfs
        ;;
    3)
        echo "Reinstalling bootloader..."
        grub-install /dev/sda
        grub-mkconfig -o /boot/grub/grub.cfg
        ;;
    4)
        echo "Resetting network..."
        cat > /etc/network/interfaces << 'EOF'
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp
EOF
        ;;
    5)
        echo "Resetting root password..."
        passwd root
        ;;
    6)
        exit 0
        ;;
esac

Emergency Boot Options

# Boot with minimal services
# Add to kernel line:
rc_parallel=no
rc_interactive=yes

# Boot to single user mode
# Add to kernel line:
single

# Boot with specific init
# Add to kernel line:
init=/bin/sh

# Skip filesystem check
# Add to kernel line:
fastboot

# Force filesystem check
# Add to kernel line:
forcefsck

Step 9: Preventive Measures

Create Boot Backup

#!/bin/sh
# Backup boot configuration

BACKUP_DIR="/root/boot-backup"
DATE=$(date +%Y%m%d)

mkdir -p $BACKUP_DIR

# Backup boot files
tar -czf $BACKUP_DIR/boot-$DATE.tar.gz /boot/

# Backup configuration
tar -czf $BACKUP_DIR/etc-$DATE.tar.gz \
    /etc/fstab \
    /etc/default/grub \
    /etc/mkinitfs/ \
    /etc/modprobe.d/

# Save partition info
fdisk -l > $BACKUP_DIR/partitions-$DATE.txt
blkid > $BACKUP_DIR/blkid-$DATE.txt

echo "Boot backup completed: $BACKUP_DIR"

Monitor Boot Health

#!/bin/sh
# Boot health check script

echo "=== Boot Health Check ==="
echo "Date: $(date)"

# Check boot partition space
echo -e "\nBoot partition usage:"
df -h /boot

# Check for kernel updates
echo -e "\nInstalled kernels:"
ls /boot/vmlinuz-* | wc -l

# Check initramfs dates
echo -e "\ninitramfs files:"
ls -la /boot/initramfs-*

# Check for errors in boot log
echo -e "\nRecent boot errors:"
dmesg | grep -i error | tail -5

# Check service failures
echo -e "\nFailed services:"
rc-status -c

Step 10: Advanced Troubleshooting

Kernel Panic Analysis

# Capture kernel panic
# Add to kernel line:
panic=30 crashkernel=128M

# Configure kdump
apk add kexec-tools
rc-update add kdump boot

# Analyze panic
# Look for:
# - Call trace
# - RIP (instruction pointer)
# - Stack dump

Boot Performance Analysis

# Install bootchart
apk add bootchart2

# Enable bootchart
# Add to kernel line:
initcall_debug printk.time=y init=/sbin/bootchartd

# Generate report
bootchart2 -o bootchart.png

# Analyze systemd-bootchart (if using systemd)
systemd-analyze
systemd-analyze blame
systemd-analyze critical-chain

Step 11: UEFI-Specific Issues

UEFI Boot Repair

# Check UEFI variables
efibootmgr -v

# Create new boot entry
efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\alpine\\grubx64.efi -L "Alpine Linux"

# Remove boot entry
efibootmgr -b 0001 -B

# Set boot order
efibootmgr -o 0001,0002,0003

# Mount EFI partition
mount -t vfat /dev/sda1 /boot/efi

Secure Boot Issues

# Check Secure Boot status
mokutil --sb-state

# Disable Secure Boot (in BIOS/UEFI)
# Or sign bootloader
sbsign --key db.key --cert db.crt --output grubx64.efi grubx64.efi.unsigned

# Enroll keys
mokutil --import my-signing-key.der

Step 12: Create Custom Recovery ISO

# Create custom recovery ISO with tools

# Install required packages
apk add alpine-sdk xorriso syslinux

# Create working directory
mkdir -p ~/recovery-iso/{boot/syslinux,tools}

# Copy kernel and initramfs
cp /boot/vmlinuz-lts ~/recovery-iso/boot/
cp /boot/initramfs-lts ~/recovery-iso/boot/

# Add recovery tools
cat > ~/recovery-iso/tools/recovery.sh << 'EOF'
#!/bin/sh
# Custom recovery script
echo "Alpine Linux Recovery Environment"
# Add recovery commands here
EOF

# Create ISO
xorriso -as mkisofs \
    -o alpine-recovery.iso \
    -b boot/syslinux/isolinux.bin \
    -c boot/syslinux/boot.cat \
    -no-emul-boot \
    -boot-load-size 4 \
    -boot-info-table \
    ~/recovery-iso/

Common Boot Error Messages

Error Solutions

“No bootable device”
- Check BIOS boot order
- Verify bootloader installation
- Check disk connections
“Kernel panic - not syncing”
- Check initramfs
- Verify root device
- Test memory
“Cannot find root device”
- Check fstab UUIDs
- Verify disk detection
- Update initramfs
“Failed to start service”
- Check service logs
- Verify dependencies
- Run service manually

Best Practices

Regular Backups: Keep boot configuration backed up
Test Changes: Test in VM before production
Document Changes: Keep boot configuration documented
Monitor Logs: Regular log checking
Update Carefully: Test kernel updates
Keep Recovery Media: Always have rescue USB/CD
Hardware Monitoring: Regular health checks

Conclusion

You now have comprehensive knowledge for diagnosing and fixing boot problems in Alpine Linux! Key skills include:

✅ Understanding boot process ✅ Diagnosing bootloader issues ✅ Fixing kernel and initramfs problems ✅ Resolving filesystem errors ✅ Hardware troubleshooting ✅ Creating recovery procedures

Remember: Systematic diagnosis is key to solving boot problems. Always keep recovery media ready! 🔧

Diagnosing Boot Problems in Alpine Linux 🔧

Table of Contents