Creating a bootable Alpine Linux USB Stick from the command line

This process applies to Alpine Linux 1.9.0 or later, and results in a run-from-ram style installation.

Requirements

In order to follow this document, you will need:

• Alpine Linux CD-ROM (Download a .iso file containing an Alpine release.)
• A USB drive (flash, external HD, card reader, etc.)

Alpine Linux from 3.3.0 and later

From Alpine Linux 3.3.0, the generated ISO’s are a hybridISO, which means they contain a valid MBR and can be raw copied directly to the USB stick, Hard Drive (If you really know what you’re doing), or burnt to a CD/DVD.

If the USB stick is in a Unix/Linux/OSX system, you will need to find out what the USB device is (I use fdisk -l), and then you can use dd to copy the iso to it:

 dd if=alpine.iso of=/dev/sdx

Boot Alpine Linux CD-ROM

1. Insert the Alpine Linux CD-ROM into a computer.
2. Boot the computer from the Alpine Linux CD-ROM.
   • This step may require changes to the BIOS settings to select booting from CD.
3. Login with the username root. No password is needed.

Determine the Device Name of the USB stick

Determine the name your computer uses for your USB stick. The following step is one way to do this.

1. After inserting the USB stick, run the command:
   • dmesg
   • At the end of this command you should see the name of your USB stick, likely starting with “sd”. (For example: “sda”).
   • The remainder of this document will assume that your USB stick is called /dev/sda
2. Use “fdisk -l” or “blkid” to check the device name by size or label

Format USB stick

Run fdisk (replacing sda with your USB stick name):

fdisk /dev/sda

1. (Optional) – Create new partition table with one FAT32 partition
   • d Delete all partitions (this may take a few steps)
   • n Create a new partition
   • p A primary partition
   • 1 Partition number 1
     • Use defaults for first and last cylinder (just press [Enter] twice).
   • t Change partition type
   • c Partition type (Win95 FAT32/LBA)
2. Verify that the primary partition is bootable
   • p Print list of partitions
   • If there is no ‘*’ next to the first partition, follow the next steps:
     • a Make the partition bootable (set boot flag)
     • 1 Partition number 1
3. w Write your changes to the device

Add Alpine Linux to the USB stick

To boot from your USB stick you need to copy the contents of the CDROM to the USB stick and make it bootable. Those two operations can be automated with the setup-bootable tool or can be done manually.

See also notes to create an Alpine Linux USB stick from within KVM with setup-bootable.

Automated

1. Run the setup-alpine script to setup network(Alpine Linux 3.3 not contain syslinux), answer the the last three questions as ‘none’
   1. Which disk(s) would you like to use: none
   2. Enter where to store configs: none
   3. Enter where to store configs: none
   4. Enter apk cache directory: none
2. Run “apk add syslinux” to install syslinux package
3. Run “modprobe vfat” to load vfat kernel module
4. Run the setup-bootable script to add Alpine Linux to the USB stick and make it bootable (replacing sda with your USB stick name):

   setup-bootable /media/cdrom /dev/sda1

   1. if “Resource busy” occurs, maybe the old files on /media/sda1, “rm /media/sda1/.alpine-release” and “reboot” to try again.

Manual

1. (Optional) – If you created a new partition above, format the USB stick with a FAT32 filesystem (replacing sda with your USB stick name):

   apk add dosfstools
   mkdosfs -F32 /dev/sda1

2. Install syslinux and MBR (replacing sda with your USB stick name):

   apk add syslinux
   dd if=/usr/share/syslinux/mbr.bin of=/dev/sda
   syslinux /dev/sda1

3. Copy the files to the USB stick (replacing sda with your USB stick name):

   mkdir -p /media/sda1 mount -t vfat /dev/sda1 /media/sda1 cd /media/cdrom cp -a .alpine-release * /media/sda1/ umount /media/sda1

4. (Optional) Remove any apkovl files that were transfered as part of the copy process. This should be done if you wish to have a fresh install. Replace sda with your USB stick name)

   mount -t vfat /dev/sda1 /media/sda1 rm /media/sda1/*.apkovl.tar.gz umount /media/sda1

Troubleshooting

Wrong Device Name

If you cannot boot from the USB stick 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 your USB stick is formatted with a filesystem other than FAT32, you might have to specify the necessary filesystem modules in the boot parameters.

To do so, mount the USB stick and change the syslinux.cfg file line from

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

to

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

in the case of an ext3 formatted partition. A similar procedure might apply to 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

See Also

Alpine Linux has some special applications that helps you to use it in the way you want.
Some of the first scripts you are suggested to use is:

• setup-alpine (Configures all basic things on your Alpine Linux)
• setup-acf (was named setup-webconf before Alpine 1.9 beta 4) (Configures ACF (webconfiguration) so you can manage your box through https)

Other useful pages

• Configure Networking
• Setting up a ssh-server (Using ssh is a good way to administer your box remotely)
• Package Management (apk) (How to add/remove packages on your Alpine)
• Init System (rc) (Configure a service to automatically boot at next reboot)
• Alpine local backup (lbu) (Permanently store your modifications in case your box needs reboot)