Create a Bootable Device: Difference between revisions

From Alpine Linux
mNo edit summary
(21 intermediate revisions by the same user not shown)
Line 1: Line 1:


This page is about creating a customizable boot device. The creation (flashing) of a default (iso) installation media is covered on the [[Installation#Flashing_.28direct_data_writing.29_the_installation_image-file_onto_a_device_or_media|Installation]] page.
This page is about creating directly customizable boot devices. The creation (flashing) of read-only (iso9660 CD filesystem) images onto installation media is covered by the [[Installation#Flashing_.28direct_data_writing.29_the_installation_image-file_onto_a_device_or_media|Installation]] page.


A customizable Alpine Linux boot medium is basically an Alpine system installed to the device in '''diskless''' or '''data''' disk-mode.
A directly customizable Alpine Linux boot medium is basically an Alpine system in '''diskless''' or '''data''' disk-mode installed to (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.


As long as the device remains writable, the local configs (.apkovl) and the package cache may also be stored on the same device.
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 =
= Requirements =


In order to follow this document, you will need:
* An Alpine Linux CD-ROM or an .iso file containing the desired Alpine release ([https://alpinelinux.org/downloads/ Download]).
 
* An Alpine Linux CD-ROM or an .iso file containing the correct 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.
* A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard.
{{Note|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.}}


= Using setup-bootable  =
= Using setup-bootable  =


The preferable method to create a custom bootable device now is to follow the [[Installation]] for a '''diskless''' or '''data''' mode system on the device, and use the <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code> script to make the device 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 <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code> script to make the device bootable.


= Manually copying Alpine files =
= Manually copying Alpine files =
Line 33: Line 27:
=== Copy ISO content to USB stick as individual files ===
=== Copy ISO content to USB stick as individual files ===


{{Warning | We assume here ''sda'' is your USB stick which would hold bootable Alpine Linux files. }}
{{Warning | We assume here ''sdU'' is your USB stick which would hold bootable Alpine Linux files. }}


The following procedure is for Alpine Linux distribution itself, if you are using other Linux distro or other operating system you should know the best how to install syslinux and where ''mbr.bin'' file is located on your filesystem.
The following procedure is for the Alpine Linux distribution itself, if you are using other Linux distro or other operating system you should know the best how to install syslinux and where ''mbr.bin'' file is located on your filesystem.


# If you created a new partition above, format the {{{1|flash medium}}} with a FAT32 filesystem (replacing sda with your {{{1|flash medium}}} name):
# If you created a new partition above, format it with a FAT32 filesystem (replacing sdU with your device name):
#: {{Cmd|apk add dosfstools<BR>mkdosfs -F32 /dev/sda1}}
#: {{Cmd|apk add dosfstools<BR>mkdosfs -F32 /dev/sdU1}}
# Install syslinux and MBR (replacing sda with your {{{1|flash medium}}} name):
# Install syslinux and MBR (replacing sdU with your device name):
#: {{Cmd|{{{|apk add syslinux<BR>dd if=/usr/share/syslinux/mbr.bin of=/dev/sda}}}<BR>syslinux /dev/sda1}}
#: {{Cmd|{{{|apk add syslinux<BR>dd if=/usr/share/syslinux/mbr.bin of=/dev/sdU}}}<BR>syslinux /dev/sdU1}}
#Copy the files to the {{{1|flash medium}}} (replacing sda with your {{{1|flash medium}}} name):
#Copy the files to the boot device (replacing sdU with your device name):
#: {{Cmd|<nowiki>mkdir -p /media/sda1
#: {{Cmd|<nowiki>mkdir -p /media/sdU1
mount -t vfat /dev/sda1 /media/sda1
mount -t vfat /dev/sdU1 /media/sdU1
cd /media/cdrom
cd /media/cdrom
cp -a .alpine-release * /media/sda1/
cp -a .alpine-release * /media/sdU1/
umount /media/sda1</nowiki>}}
umount /media/sdU1</nowiki>}}
# (''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 {{{1|flash medium}}} name)
# (''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 sdU with your device name)
#: {{Cmd|<nowiki>mount -t vfat /dev/sda1 /media/sda1
#: {{Cmd|<nowiki>mount -t vfat /dev/sdU1 /media/sdU1
rm /media/sda1/*.apkovl.tar.gz
rm /media/sdU1/*.apkovl.tar.gz
umount /media/sda1</nowiki>}}
umount /media/sdU1</nowiki>}}




Line 57: Line 51:
==== Wrong Device Name ====
==== Wrong Device Name ====


If you cannot boot from the {{{1|flash medium}}} and you see something like:
If you cannot boot from the boot device and you see something like:
  Mounting boot media failed.
  Mounting boot media failed.
  initramfs emergency recovery shell launched. Type 'exit' to continue boot
  initramfs emergency recovery shell launched. Type 'exit' to continue boot
Line 68: Line 62:
==== Non-FAT32 Filesystems ====
==== Non-FAT32 Filesystems ====


When your {{{1|flash medium}}} is formatted with a filesystem other than FAT32, you might have to specify the necessary filesystem modules in the boot parameters.
===== Diskless and data mode booting =====


To do so, mount the {{{1|flash medium}}} and change the {{Path|syslinux.cfg}} file line from
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]]
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).


===== 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 ==
== Finishing installation ==
Line 87: Line 85:


  # mount | grep /media
  # 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)
  /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).
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/sda1
  # mount -o remount,rw /media/sdU1
  # mkdir /media/sda1/cache
  # mkdir /media/sdU1/cache
  # setup-apkcache /media/sda1/cache
  # setup-apkcache /media/sdU1/cache
  # ls -l /etc/apk/cache
  # ls -l /etc/apk/cache
  lrwxrwxrwx    1 root    root            17 Oct 19 13:16 /etc/apk/cache -> /media/sda1/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 ''sda1'' to hold our system customization.
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
  # setup-alpine
  ...
  ...
  Which disk(s) would you like to use? (or '?' for help or 'none') [none]  
  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 where to store configs ('floppy', 'sdU1', 'usb' or 'none') [sdU1]:  
  Enter apk cache directory (or '?' or 'none') [/media/sda1/cache]:
  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:
After the installer finished you can see how many created/modified files are detected and will be added to the backup:
Line 110: Line 108:
  59
  59
  # lbu commit
  # lbu commit
  # ls -l /media/sda1/*apkovl.tar.gz
  # ls -l /media/sdU1/*apkovl.tar.gz
  -rwxr-xr-x    1 root    root          9591 Oct 19 15:23 /media/sda1/foo.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.
Now all the customization are saved into the ''foo.apkovl.tar.gz'' compressed tarball on the USB stick itself.
Line 121: Line 119:
  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]]

Revision as of 18:09, 18 May 2021

This page is about creating directly customizable boot devices. The creation (flashing) of read-only (iso9660 CD filesystem) images onto installation media is covered by the Installation page.

A directly customizable Alpine Linux boot medium is basically an Alpine system in diskless or data disk-mode installed to (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

This process applies to Alpine Linux 1.9.0 or later.

It describes how to manually create a custom (writable) USB boot device.


Copy ISO content to USB stick as individual files

Warning: We assume here sdU is your USB stick which would hold bootable Alpine Linux files.


The following procedure is for the Alpine Linux distribution itself, if you are using other Linux distro or other operating system you should know the best how to install syslinux and where mbr.bin file is located on your filesystem.

  1. If you created a new partition above, format it with a FAT32 filesystem (replacing sdU with your device name):

    apk add dosfstools
    mkdosfs -F32 /dev/sdU1

  2. Install syslinux and MBR (replacing sdU with your device name):

    apk add syslinux
    dd if=/usr/share/syslinux/mbr.bin of=/dev/sdU
    syslinux /dev/sdU1

  3. Copy the files to the boot device (replacing sdU with your device name):

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

  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 sdU with your device name)

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


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.