Create a Bootable Device

This page is about creating customizable boot device for diskless or data disk-mode Alpine Linux using a writable filesystem i.e. non-iso9660. This allows Local Backup Utility(lbu) utility to store local customizations using apkovl files and local package cache in the customizable boot device. It also allows upgrading the kernel modules and firmware, that is used to boot the diskless system, with the update-kernel script.

Note: These instructions are exclusively for x86_64 and x86. For ARM boards, see Alpine on ARM.

Requirements

An Alpine Linux Installation Media, can be CD/DVD/USB or an alpine-standard-3.21.3-x86_64.iso file or an compressed tarball file containing the desired Alpine release (Download) on an existing Alpine Linux machine.
A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard which will be used as a customizable boot device.

Diskless installation on customizable boot device

Setup-bootable script is the preferred method to create a directly customizable boot device on a FAT32 filesystem. For other filesystems refer Manually copying Alpine files.

Using setup-bootable

Follow the below steps to use the Setup-bootable script to create a directly customizable boot device on a FAT32 filesystem. If you have an existing Alpine Linux machine and iso file, proceed directly to step 2.

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.
Ensure that customizable boot device is already plugged in or installed. Install the necessary tools to prepare the customizable bootable device so that it doesn't have weird stuff that affects later:
# apk add dosfstools wipefs util-linux

Warning: Do not proceed if you're unsure of device name or if you have valuable data on your USB drive.The instructions in this section use /dev/sda. Alter the device name i.e /dev/sda as needed.
Run lsblk to identify the device name for your bootable device. Let's say it's /dev/sda for this example, change as needed. Issue the below command to nuke EVERYTHING on the disk /dev/sda:
# wipefs --all /dev/sda
Create a partition sda1 with the desired size, set the type to win95 fat, and set the bootable flag on it. Format the newly created partition:
# mkfs.vfat /dev/sda1
Figure out where your install media files are mounted. if you run a mount command, you should see a read only(ro) mount for something like /media/cdrom or /media/usb or something else, depending on your environment. Let's use /media/cdrom for the install media files and /dev/sda1 for the customizable boot device:
# setup-bootable -v /media/cdrom /dev/sda1
Alternatively, if you have .iso file, issue the command:
# setup-bootable -v alpine-standard-3.21.3-x86_64.iso /dev/sda1
Once the above steps are complete, reboot the system with only the Customizable boot device inserted and Proceed to Finshing diskless installation section to complete the diskless installation.

Manually copying Alpine files

If you do not want to use Setup-bootable script or need non-FAT32 partitions, you can manually create a customizable boot device by manually copying Alpine Linux Files from the ISO/tarball and install the bootloader to make the device bootable.

This method is written for copying files from an Alpine ISO file but also works for Alpine tarballs (.tar.gz files) with a one line tweak (see below).

Install some prerequisites. (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
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
Make sure that the target drive's existing partitions, if any, are not mounted:
umount -q $mydev?
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
Format the new FAT32 partition with a FAT32 filesystem:
mkdosfs -F32 ${mydev}1
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
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
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
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
(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
Proceed to Finshing diskless installation section to complete the diskless installation.

Finshing diskless installation

Boot using the customizable boot device i.e previously created Alpine Linux bootable USB medium. Prepare customizable boot device to hold local customizations before running the setup-alpine script to finish the installation.

First find out where booted USB media is mounted, the location could vary.

# mount | grep /media
/dev/sda1 on /media/sda1 type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro)

Create local directory on USB media to hold Local Package Cache for storing the apk files.

# mount -o remount,rw /media/sda1
# mkdir /media/sda1/cache
# setup-apkcache /media/sda1/cache
# ls -l /etc/apk/cache
lrwxrwxrwx    1 root     root            17 Oct 19 13:16 /etc/apk/cache -> /media/sda1/cache

Run setup-alpine once again to complete the Installation until the base configuration step. When the Disk & Install option appears, accept the choices as follows:

Which disk(s) would you like to use? (or '?' for help or 'none') [none] Enter where to store configs ('floppy', 'sda1', 'usb' or 'none') [sda1]: Enter apk cache directory (or '?' or 'none') [/media/sda1/cache]:

After the installer finished you can see how many created/modified files are detected and will be added to the backup:

# lbu status
# lbu status | wc -l
59
# lbu commit
# ls -l /media/sda1/*apkovl.tar.gz
-rwxr-xr-x    1 root     root          9591 Oct 19 15:23 /media/sda1/foo.apkovl.tar.gz

Now all the customization are saved into the foo.apkovl.tar.gz compressed tarball on the customizable boot device itself.

Test/verify by rebooting and seeing that your alpine setup is preserved in the customizable boot device.

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.