Skip to content

RESCUE-MODE.md

Latest commit

 

History

History
325 lines (237 loc) · 8.73 KB

RESCUE-MODE.md

File metadata and controls

325 lines (237 loc) · 8.73 KB

Alpine Rescue Mode

The Alpine Rescue Mode provides a lightweight, network-bootable Linux environment with SSH access for system recovery, debugging, and maintenance operations.

Features

  • Zero-touch boot: Automatically boots via PXE into Alpine Linux
  • SSH ready: OpenSSH installed and configured automatically
  • Customizable access: Configure SSH keys and root password externally
  • Network configured: DHCP networking set up automatically
  • Rescue tools: Common disk and filesystem utilities pre-installed
  • Lightweight: Alpine Linux minimal footprint (~300MB RAM)

Boot Process

  1. Machine PXE boots and selects "Alpine Rescue" from menu
  2. iPXE loads Alpine Linux kernel and initrd from HTTP server
  3. Alpine boots with custom apkovl overlay
  4. Overlay automatically:
    • Installs OpenSSH
    • Configures SSH for root login
    • Sets root password (if configured)
    • Installs SSH keys (if configured)
    • Displays IP address and instructions
  5. System is ready for SSH access

Quick Start

Default Mode (Manual Password Setup)

  1. Boot into rescue mode from PXE menu
  2. System displays IP address on console
  3. Login as root (no password)
  4. Set password: passwd
  5. SSH from another machine: ssh root@<IP>

Customized Mode (Automatic Setup)

  1. Configure SSH access before generating apkovl:

    # Set root password
echo "YourSecurePassword" > config/alpine-rescue/root_password
chmod 600 config/alpine-rescue/root_password

# Add SSH keys
cp ~/.ssh/id_ed25519.pub config/alpine-rescue/authorized_keys
chmod 644 config/alpine-rescue/authorized_keys

  2. Generate the rescue apkovl:

    ./scripts/create-alpine-rescue-apkovl.sh

  3. Boot into rescue mode

  4. SSH is immediately available: ssh root@<IP>

Configuration

The rescue mode can be customized by placing configuration files in the config directory:

Config Directory

Default location: config/alpine-rescue/

This directory is created automatically when you run the script. Files placed here are included in the apkovl overlay.

Configuration Files

root_password

Purpose: Set root password automatically on boot

Format: Plain text file containing the password

Example:

echo "MySecurePassword123!" > config/alpine-rescue/root_password
chmod 600 config/alpine-rescue/root_password

Security:

  • File should have 600 permissions (read/write for owner only)
  • Use a strong password
  • Don't commit this file to version control

authorized_keys

Purpose: Enable SSH key-based authentication

Format: Standard SSH authorized_keys format (one key per line)

Example:

# Copy your public key
cp ~/.ssh/id_ed25519.pub config/alpine-rescue/authorized_keys
chmod 644 config/alpine-rescue/authorized_keys

# Or add multiple keys
cat ~/.ssh/id_ed25519.pub >> config/alpine-rescue/authorized_keys
cat ~/.ssh/id_rsa.pub >> config/alpine-rescue/authorized_keys

Security:

  • File should have 644 permissions
  • Only include trusted public keys
  • Keys are installed to /root/.ssh/authorized_keys in the rescue environment

Regenerating After Changes

After modifying any configuration files, regenerate the apkovl:

./scripts/create-alpine-rescue-apkovl.sh

The updated apkovl will be deployed automatically on the next boot.

Available Tools

The Alpine rescue environment includes common system recovery tools:

Disk Tools

  • fdisk - Partition table manipulation
  • parted - Advanced partitioning
  • e2fsck - ext2/ext3/ext4 filesystem check
  • resize2fs - Resize ext2/ext3/ext4 filesystems

Filesystem Tools

  • mount / umount - Mount filesystems
  • mkfs.* - Create filesystems
  • blkid - Identify block devices

Network Tools

  • wget / curl - Download files
  • ping - Network connectivity testing
  • ip - Network configuration
  • netstat - Network statistics

Package Management

  • apk - Alpine package manager
    • apk add <package> - Install packages
    • apk search <term> - Search packages
    • apk update - Update package index

Common Rescue Operations

Mounting and Accessing Local Disk

# List all disks and partitions
fdisk -l

# Mount a partition
mkdir -p /mnt/root
mount /dev/sda1 /mnt/root

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

# Exit chroot and unmount
exit
umount /mnt/root/sys /mnt/root/proc /mnt/root/dev
umount /mnt/root

Resizing a Filesystem

# Check filesystem first
e2fsck -f /dev/sda1

# Resize filesystem to maximum available space
resize2fs /dev/sda1

Installing Additional Tools

# Update package index
apk update

# Install additional tools
apk add vim nano htop

Downloading Files from Network

# Download with wget
wget http://example.com/file.tar.gz

# Download with curl
curl -O http://example.com/file.tar.gz

Technical Details

Boot Parameters

The rescue mode is configured via iPXE boot parameters:

# Alpine kernel parameters
set kernel_params initrd=initrd
set kernel_params ${kernel_params} console=tty0 console=ttyS0,115200
set kernel_params ${kernel_params} ip=dhcp
set kernel_params ${kernel_params} modloop=http://${http_server}/boot/alpine/amd64/modloop
set kernel_params ${kernel_params} alpine_repo=http://dl-cdn.alpinelinux.org/alpine/latest-stable/main
set kernel_params ${kernel_params} modules=loop,squashfs,sd-mod,usb-storage

# Load rescue configuration overlay
set kernel_params ${kernel_params} apkovl=http://${http_server}/boot/alpine/alpine-rescue.apkovl.tar.gz

# Boot Alpine
kernel http://${http_server}/boot/alpine/amd64/vmlinuz ${kernel_params}
initrd http://${http_server}/boot/alpine/amd64/initrd
boot

Apkovl Structure

The apkovl (Alpine overlay) is a tar.gz archive containing configuration files that Alpine loads on boot:

alpine-rescue.apkovl.tar.gz
├── etc/
│   ├── local.d/
│   │   └── rescue-setup.start       # Auto-start script
│   └── runlevels/
│       └── default/
│           └── local -> /etc/init.d/local
└── root/
    ├── .profile                      # Shell profile
    └── .ssh/
        └── authorized_keys           # SSH keys (if configured)

Auto-start Script

The rescue-setup.start script runs automatically on boot:

  1. Sets root password (if configured)
  2. Installs OpenSSH: apk add openssh
  3. Configures SSH for root login
  4. Starts SSH service
  5. Displays welcome message with IP address

RAM Requirements

  • Minimum: 1GB RAM
  • Recommended: 2GB RAM
  • Alpine runs entirely in RAM (tmpfs = 50% of total RAM)
  • Base system: ~100MB
  • With tools and SSH: ~300MB total

Troubleshooting

SSH Connection Refused

Problem: Cannot connect via SSH after boot

Possible causes:

  1. Root password not set (if not using authorized_keys)
    • Solution: Login on console and run passwd
  2. Network connectivity issues
    • Solution: Check DHCP, verify IP with ip addr
  3. SSH service not started
    • Solution: rc-service sshd start

Cannot Find Disk

Problem: fdisk -l shows no disks

Possible causes:

  1. Driver not loaded
    • Solution: modprobe <driver> (e.g., modprobe nvme)
  2. Disk not connected
    • Solution: Check physical connections

No Network Connectivity

Problem: No IP address or cannot reach network

Possible causes:

  1. DHCP not working
    • Solution: Manual IP: ip addr add 10.1.21.100/23 dev eth0
  2. Wrong interface
    • Solution: Check with ip link and configure correct interface

Out of RAM

Problem: "No space left on device" errors

Possible causes:

  1. Downloaded large files to tmpfs
    • Solution: Use external storage: mount /dev/sda1 /mnt && cd /mnt
  2. Insufficient RAM
    • Solution: Add more RAM to machine (2GB recommended)

Security Considerations

  1. Temporary environment: Rescue mode runs in RAM - all changes are lost on reboot
  2. Root access: Full root access is provided for recovery operations
  3. Network accessible: SSH is open to network - use strong passwords/keys
  4. Password storage: Config files contain plaintext passwords - protect them
  5. Boot server security: Apkovl is downloaded via HTTP - secure your boot server

Best Practices

  • Use SSH keys instead of passwords when possible
  • Set strong root passwords
  • Protect config directory with proper permissions (chmod 700)
  • Don't commit sensitive config files to version control
  • Use network segmentation to limit rescue mode access
  • Review SSH logs after rescue operations

See Also