Create a Bootable Device: Difference between revisions

From Alpine Linux
(Add note for potential issue with device file and tip for syslinux install)
 
(52 intermediate revisions by 10 users not shown)
Line 1: Line 1:
== Creating a bootable Alpine Linux USB Stick with UNetbootin ==
{{Note|These instructions are exclusively for x86_64 and x86. For ARM boards, see [[Alpine_on_ARM#Preparing_installation_media]].}}


UNetbootin is a graphical tool that allows you to create bootable Live USB drives for Ubuntu, Fedora, and other Linux distributions without burning a CD. UNetbootin is available for many distributions and Windows. This process applies to all versions of Alpine Linux, and results in a '''run-from-ram''' style installation.
This page is about creating directly customizable boot devices. If you are looking for instructions on creating (flashing) read-only (iso9660 "CD" filesystem) images onto installation media, see the [[Installation#Flashing_.28direct_data_writing.29_the_installation_image-file_onto_a_device_or_media|Installation]] page instead.


=== Requirements ===
A directly customizable Alpine Linux boot medium is basically an Alpine system in '''[[Installation#Diskless_Mode|diskless]]''' or '''[[Installation#Data_Disk_Mode|data]]''' disk-mode installed to (and booting from) a device with a writable filesystem. It allows to also upgrade the kernel with its modules and firmware that is used to boot the system with the <code>[[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs|update-kernel]]</code> script.
To create a bootable Alpine Linux USB drive, you will need:


* An Alpine Linux ISO image file ([http://alpinelinux.org/downloads Download])
The more general local customizations, the configs (.apkovl) and the package cache, may of course also be stored on the same device, as long as the hardware is not being set to be write-locked by a hardware switch.
* A partitioned and formatted USB drive
* [http://unetbootin.sourceforge.net/ UNetbootin]


=== Process ===
= Requirements =


After the launch of UNetbootin, click the '''Diskimage''' radio button, and then the '''...''' button to select the Alpine ISO image.
* An Alpine Linux CD-ROM or an .iso file containing the desired Alpine release ([https://alpinelinux.org/downloads/ Download]).
* A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard.


[[File:Unetbootin.png|size=400]]
= Using setup-bootable  =


When you selected your USB device under '''Device'' and press '''OK''' to proceed. When UNetbootin is done, your USB drive is ready to use.
This is now the preferable method to create a directly customizable bootable device.


== Creating a bootable Alpine Linux USB Stick from the command line ==
It consists an [[Installation]] of a '''diskless''' or '''data''' mode system with configs and package cache on the target device, and using the <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code> script to make the device bootable.


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


{{Warning|This process can potentially totally or partly erase the contents of your hard drive. For this reason, it is recommended to do this procedure using VirtualBox rather than your own computer.}}
If you can't/won't use '''setup-bootable''', you can manually create a customizable (writable) USB boot device instead.


=== Requirements ===
=== Copying ISO/tarball contents to a USB stick ===
In order to follow this document, you will need:
 
* Alpine Linux CD-ROM ([[Downloads|Download]] a .iso file containing an Alpine release.)
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).
* A USB drive (flash, external HD, card reader, etc.)
 
# 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.)
#: {{Cmd|apk add dosfstools<BR>apk add syslinux}}
# Set the environment variable 'mydev' to the [https://en.wikipedia.org/wiki/Device_file 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 <code>${mydev}1</code> with <code>${mydev}p1</code> below.}}
#: {{Cmd|<nowiki>mydev=/dev/sdU</nowiki>}}
# Make sure that the target drive's existing partitions, if any, are not mounted:
#: {{Cmd|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):
#: {{Cmd|<nowiki>fdisk -w always $mydev <<EOF
  o
  n
  p
  1
  2048
  -0
  t
  0c
  a
  w
EOF</nowiki>}}
# Format the new FAT32 partition with a FAT32 filesystem:
#: {{Cmd|<nowiki>mkdosfs -F32 ${mydev}1</nowiki>}}
# Copy the [https://wiki.syslinux.org/wiki/index.php?title=Mbr syslinix 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):
#: {{Cmd|<nowiki>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=$mydev</nowiki>}}
# 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 <code>--install</code> flag):
#: {{Cmd|syslinux ${mydev}1}}
# Copy the Alpine files to the FAT32 filesystem (to copy the contents of an Alpine {{Path|.tar.gz}} tarball instead of copying {{Path|/media/cdrom}}, set <code>$alpinetarball</code> to the path to the tarball and replace the 'cp' line with: <code>tar -p -s --atime-preserve --same-owner --one-top-level=/media/$mydevname -zxvf "$alpinetarball"</code>):
#: {{Cmd|<nowiki>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</nowiki>}}
# (''Optional'') Remove any .apkovl overlay files that were transferred as part of the copy process. Do this if you want an unmodified, vanilla install.
#: {{Cmd|<nowiki>mount -t vfat ${mydev}1 /media/$mydevname
rm /media/$mydevname/*.apkovl.tar.gz
umount /media/$mydevname</nowiki>}}
 
 
=== 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 {{Path|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 <code>cat /proc/partitions</code> to see the available disks (i.e. 'sda' or 'sdb')
 
==== Non-FAT32 Filesystems ====
 
===== Diskless and data mode booting =====
 
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 <code>update-kernel</code>. See: [[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs]]
 
===== Sys mode booting  =====
 
Mount the boot device and edit the {{Path|syslinux.cfg}} file.
 
Then locate the "append" line, and change the <code>alpine_dev=</code> setting to match the used filesystem and add the filesystem's kernel module to the <code>modules=</code> 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.)
 
== Finishing installation ==
 
After one has booted the previously created Alpine Linux bootable USB medium, one has to prepare USB stick to hold local customizations and run ''setup-alpine'' to finish the installation.
 
First let's find out where is our just booted USB media mounted, the location could vary.
 
# mount | grep /media
/dev/sdU1 on /media/sdU1 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 APK cache (see [[Alpine_Linux_package_management#Local_Cache|APK Local Cache]] for details).
 
# mount -o remount,rw /media/sdU1
# mkdir /media/sdU1/cache
# setup-apkcache /media/sdU1/cache
# ls -l /etc/apk/cache
lrwxrwxrwx    1 root    root            17 Oct 19 13:16 /etc/apk/cache -> /media/sdU1/cache
 
Now run ''setup-alpine'' and proceed until a question about local disk selection - in ''diskless'' mode we won't use any disk (ie. our bootable media files is basically untouched) and we are going to use ''sdU1'' to hold our system customization.
 
# setup-alpine
...
Which disk(s) would you like to use? (or '?' for help or 'none') [none]
Enter where to store configs ('floppy', 'sdU1', 'usb' or 'none') [sdU1]:
Enter apk cache directory (or '?' or 'none') [/media/sdU1/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/sdU1/*apkovl.tar.gz
-rwxr-xr-x    1 root    root          9591 Oct 19 15:23 /media/sdU1/foo.apkovl.tar.gz
 
Now all the customization are saved into the ''foo.apkovl.tar.gz'' compressed tarball on the USB stick itself.
 
= Troubleshooting =


{{:Include:Copying Alpine to Flash|USB stick}}
=== Slow USB Devices ===
=== 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.
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'''
  append initrd=/boot/grsec.gz alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet '''waitusb=3'''


== See Also ==
 
{{:Include:Installing_Alpine_see_also}}
=== 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.
 
 
 


[[Category:Installation]]
[[Category:Installation]]

Latest revision as of 18:38, 28 November 2023

Note: These instructions are exclusively for x86_64 and x86. For ARM boards, see Alpine_on_ARM#Preparing_installation_media.

This page is about creating directly customizable boot devices. If you are looking for instructions on creating (flashing) read-only (iso9660 "CD" filesystem) images onto installation media, see the Installation page instead.

A directly customizable Alpine Linux boot medium is basically an Alpine system in diskless or data disk-mode installed to (and booting from) a device with a writable filesystem. It allows to also upgrade the kernel with its modules and firmware that is used to boot the system with the update-kernel script.

The more general local customizations, the configs (.apkovl) and the package cache, may of course also be stored on the same device, as long as the hardware is not being set to be write-locked by a hardware switch.


Requirements

  • An Alpine Linux CD-ROM or an .iso file containing the desired Alpine release (Download).
  • A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard.

Using setup-bootable

This is now the preferable method to create a directly customizable bootable device.

It consists an Installation of a diskless or data mode system with configs and package cache on the target device, and using the setup-bootable script to make the device bootable.

Manually copying Alpine files

If you can't/won't use setup-bootable, you can manually create a customizable (writable) USB boot device instead.

Copying ISO/tarball contents to a USB stick

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).

  1. 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
    apk add 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/sdU

  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

  6. Copy the syslinix 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 of copying /media/cdrom, set $alpinetarball to the path to the tarball and replace the 'cp' line with: tar -p -s --atime-preserve --same-owner --one-top-level=/media/$mydevname -zxvf "$alpinetarball"):

    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. (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

Diskless and data mode booting

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. See: Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs

Sys mode booting

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.)

Finishing installation

After one has booted the previously created Alpine Linux bootable USB medium, one has to prepare USB stick to hold local customizations and run setup-alpine to finish the installation.

First let's find out where is our just booted USB media mounted, the location could vary.

# mount | grep /media
/dev/sdU1 on /media/sdU1 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 APK cache (see APK Local Cache for details).

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

Now run setup-alpine and proceed until a question about local disk selection - in diskless mode we won't use any disk (ie. our bootable media files is basically untouched) and we are going to use sdU1 to hold our system customization.

# setup-alpine
...
Which disk(s) would you like to use? (or '?' for help or 'none') [none] 
Enter where to store configs ('floppy', 'sdU1', 'usb' or 'none') [sdU1]: 
Enter apk cache directory (or '?' or 'none') [/media/sdU1/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/sdU1/*apkovl.tar.gz
-rwxr-xr-x    1 root     root          9591 Oct 19 15:23 /media/sdU1/foo.apkovl.tar.gz

Now all the customization are saved into the foo.apkovl.tar.gz compressed tarball on the USB stick itself.

Troubleshooting

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.