Create a Bootable Device

This page is about preparing a directly customizable boot media or customizable boot device for Alpine Linux, i.e a USB-Stick/CompactFlash/SDCard or SSD/NVMe harddisk based boot device with a writable filesystem i.e. non-iso9660.

A customizable boot device is basically an Alpine system in diskless or data disk-mode installed to (and booting from) a device with a writable filesystem. A customizable boot device allows Local Backup Utility(lbu) utility to store local customizations as apkovl file and local package cache. It also allows to upgrade the kernel with its modules and firmware that is used to boot the system with the update-kernel script.

Requirements

• An Alpine Linux installation media, can be CD/DVD/USB or an .isofile like alpine-standard-3.22.2-x86_64.iso or an compressed tarball file like alpine-rpi-3.22.2-aarch64.tar.gz or .img.gz file like alpine-rpi-3.22.2-aarch64.img.gz containing the desired Alpine release.
• A device like an USB drive (flash, external HD/SSD/NVMe, card reader, etc.) or a CF "CompactFlash", or SDcard which will be used as a customizable boot device.

Preparing customizable boot device

To create a customizable boot device on a FAT32 filesystem for x86_64 and x86 using setup-bootable script is the preferred method. For Raspberry Pi, using the image file i.e img.gz and following the installation media preparation steps with the SD card results in a customizable boot device. For other filesystems/architectures refer Manually copying Alpine files section.

Using setup-bootable

Customizable boot device can be created on a FAT32 filesystem using the Setup-bootable script by following these steps. If you have an existing Alpine Linux machine and iso file, proceed directly to step 2.

1. Complete the Installation until the base configuration step by booting from an Alpine Linux installation media. Perform the initial execution of setup-alpine as described in the base configuration step answering "none" to all disk-related questions.
2. Ensure that customizable boot device is plugged in before installing the necessary tools:

   # apk add dosfstools util-linux

   

   Warning: Use lsblk to identify the correct device name for your customizable boot device and use it instead of /dev/sdX used here. If you are unsure, do not proceed, seek support.

   
   

3. To nuke EVERYTHING on the disk /dev/sdX, so it doesn't have weird stuff that affects later, issue the command:

   # wipefs --all /dev/sdX

4. Create a partition sdXY with the desired size, set the type to win95 fat, and set the bootable flag on it, or use the following command to use entire disk:

   # echo 'type=c, bootable' | sfdisk /dev/sdX

5. Format the newly created partition:

   # mkfs.vfat /dev/sda1

6. If booted from an Alpine Linux installation media, use mount command to figure out where the install media files are mounted. A read only(ro) mount will appear for /media/cdrom or /media/usb or something else, depending on your environment and adjust media/cdrom in the command :

   # setup-bootable -v /media/cdrom /dev/sdXY

7. Alternatively, if you have an existing Alpine Linux machine with .iso file, issue the command:

   # setup-bootable -v alpine-standard-3.22.2-x86_64.iso /dev/sdXY

Manually copying Alpine files

The customizable boot device can be created by manually copying Alpine Linux files from both ISO(.iso) and tarballs (.tar.gz files) with a one line tweak (see below).

1. Install some prerequisites. The syslinux is required only for x86_64 and x86. (If you're not currently using Alpine Linux then you probably have these installed already, otherwise you'll have to figure out how to install them.)

   # apk add dosfstools syslinux

2. Set the environment variable 'mydev' to the device file name of the USB stick that Alpine Linux is to be installed to:

   

   Warning: BE SURE TO GET THIS RIGHT OR ELSE YOU COULD OVERWRITE THE WRONG DISK!

   
   

   Note: If USB stick's device name ends in a digit, you might have to replace all instances of ${mydev}1 with ${mydev}p1 below.

   mydev=/dev/sda

3. Make sure that the target drive's existing partitions, if any, are not mounted:

   umount -q $mydev?

4. Copy and paste the following as a single command to wipe the target drive, create an MBR partition table, and create a single FAT32 partition (you can ignore any "Partition #1 contains a vfat signature." warning message):

   fdisk -w always $mydev <<EOF o n p 1 2048 -0 t 0c a w EOF

5. Format the new FAT32 partition with a FAT32 filesystem:

   mkdosfs -F32 ${mydev}1

   Tip: For ARM boards like Raspberry Pi, ignore the next three steps and go to the 9th step related to tarball. Refer Alpine on ARM for more information.

6. Copy the syslinux executable boot code into the bootstrap code area of the MBR boot sector (if you're not currently using Alpine Linux you may need to adjust the path to syslinux's mbr.bin file):

   dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=$mydev

7. Install the syslinux bootloader files onto the FAT32 filesystem. (Ignore the "Hidden (2048) does not match sectors (62)" messages - modern systems use the partition table. If you are getting "no previous syslinux boot sector found" error, try adding --install flag):

   syslinux ${mydev}1

8. Copy the Alpine files to the FAT32 filesystem (to copy the contents of an Alpine .tar.gz tarball instead, see next item):

   mydevname=$(basename $mydev)1 mkdir -p /media/$mydevname mount -t vfat ${mydev}1 /media/$mydevname cp -aT /media/cdrom /media/$mydevname # -T to copy hidden files umount /media/$mydevname

9. If you instead want to copy the contents of an Alpine .tar.gz tarball, do this:

   mydevname=$(basename $mydev)1 mytarball=/path/to/alpine-tarball.tar.gz mkdir -p /media/$mydevname mount -t vfat ${mydev}1 /media/$mydevname tar -p -s --atime-preserve --same-owner --one-top-level=/media/$mydevname -zxvf $mytarball umount /media/$mydevname

10. (Optional) Remove any .apkovl overlay files that were transferred as part of the copy process. Do this if you want an unmodified, vanilla install.

    mount -t vfat ${mydev}1 /media/$mydevname rm /media/$mydevname/*.apkovl.tar.gz umount /media/$mydevname

Troubleshooting

Wrong Device Name

If you cannot boot from the boot device and you see something like:

Mounting boot media failed.
initramfs emergency recovery shell launched. Type 'exit' to continue boot

then it is likely that the device name in syslinux.cfg is wrong. You should replace the device name in this line:

append initrd=/boot/grsec.gz alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet

with the proper device name.

• For boot from USB, the device name should be 'usbdisk' (as shown above)
• For other options, you can run cat /proc/partitions to see the available disks (i.e. 'sda' or 'sdb')

Non-FAT32 Filesystems

When the boot device is formatted with a filesystem other than those supported by default, the necessary initfs features need to be added to the modloop using update-kernel script.

Mount the boot device and edit the syslinux.cfg file.

Then locate the "append" line, and change the alpine_dev= setting to match the used filesystem and add the filesystem's kernel module to the modules= list.

For example, change

append [...] alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet

to

append [...] alpine_dev=usbdisk:ext4 modules=loop,cramfs,sd-mod,usb-storage,ext4 quiet

in the case of an ext4 formatted partition. (Or correspondingly for other filesystems, if they are supported by syslinux and the Alpine Linux kernel.)

Slow USB Devices

Specifying the 'waitusb=X' option at the end of the syslinux.cfg line might help with certain USB devices that take a bit longer to register. X stands for the amount of seconds kernel will wait before looking for the installation media.

append initrd=/boot/grsec.gz alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet waitusb=3

CF card readers

Some CF card readers have problems with the faster CF cards on the market. If you experience problems booting the CF card even after checking BIOS settings, you may need to use an older card.

Also, many CF card readers don't support DMA correctly, so you may need to add nodma to the append line of the syslinux.cfg file.

See Also

• Diskless Mode
• Local Package Cache
• Alpine local backup
• update-kernel script