Create a Bootable Device: Difference between revisions
(Added manual steps to create bootable USB) |
Prabuanand (talk | contribs) (rephrased sentence to add clarity. Added reference to Fat32 only information. added links) |
||
(75 intermediate revisions by 22 users not shown) | |||
Line 1: | Line 1: | ||
{{Note|These instructions are exclusively for x86_64 and x86. For ARM boards, see [[Alpine_on_ARM#Preparing_installation_media|Alpine on ARM]].}} | |||
This page is about creating customizable boot devices for '''[[Installation#Diskless_Mode|diskless]]''' or '''[[Installation#Data_Disk_Mode|data]]''' disk-mode Alpine Linux using a writable filesystem i.e. not iso9660, so that local customizations like apkovl files and cached packages can be stored. It allows to also upgrade the kernel with its modules and firmware that is used to boot the system with the [[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs|update-kernel]] script. | |||
== Requirements == | |||
* An Alpine Linux [[Installation#Preparing_installation_media|Installation Media]], can be CD/DVD/USB. | |||
* A customizable boot device that can be a USB-Stick/CompactFlash/SDCard etc., or harddisk partition for the '''[[Installation#Diskless_Mode|diskless]]''' or '''[[Installation#Data_Disk_Mode|data]]''' mode Alpine linux. | |||
== Using setup-bootable == | |||
[[Alpine_setup_scripts#setup-bootable|setup-bootable]] script is the preferred method to create a directly customizable bootable device on a FAT32 filesystem. For other filesystems refer [[#Manually copying Alpine files|Manually copying Alpine files]]. | |||
Complete the [[#Installation_Step_Details|Installation]] until the [[#Base_configuration|base configuration]] step by booting from an Alpine Linux [[Installation#Preparing_installation_media|Installation Media]]. 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: | |||
{{Cmd|# apk add dosfstools wipefs util-linux}} | |||
Run <Code>lsblk</Code> to figure out what the disk to turn into your bootable device. Let's say it's /dev/sda for this example, change as needed: | |||
{{Warning|The below step will nuke EVERYTHING on the disk /dev/sda. Do not proceed if you're unsure or if you have valuable data.}} | |||
{{Cmd|# wipefs --all /dev/sda}} | |||
[[Setting_up_disks_manually#Creating_partitions|Create a partition]] sda1 with the desired size, set the type to win95 fat, and set the bootable flag on it. [[Filesystems#Formatting_Partitions|Format]] the newly created partition. Alter the device name i.e{{Path|/dev/sda1}} as needed. | |||
{{cmd|mkfs.vfat /dev/sda1}} | |||
Figure out where your install media files are mounted. if you run a {{ic|df}} command, you should see a read only 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: | |||
''''' | {{Cmd|# setup-bootable -v /media/cdrom /dev/sda1}} | ||
After that's done, remove [[Installation#Preparing_installation_media|Installation Media]] and [[Installation#Reboot|reboot]] the system. | |||
{{ | Once the system boots from the customizable boot device '''{{path|/dev/sda1}}''', login as root and run <code>setup-alpine</Code> once again to complete the [[#Installation_Step_Details|Installation]] until the [[#Base_configuration|base configuration]] step. | ||
# setup-alpine | |||
... | |||
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]: | |||
For the question on disk to use, select '''none'''. | |||
The script will then ask about storing configs. Choose the customizable boot device.('sda1' in this example). | |||
Then the script will ask you for apk cache directory, accept the default or type as follows i.e {{Path|/media/sda1/cache}}. Refer [[Alpine_Linux_package_management#Local_Cache|APK Local Cache]] for more details. | |||
Always remember to run <Code>lbu ci</Code> to commit the above changes to disk. | |||
{{Cmd|# lbu ci}} | |||
Test/verify by rebooting and seeing that your alpine setup is preserved in the customizable boot device. | |||
== Manually copying Alpine files == | |||
If you do not want to use <Code>Setup-bootable</Code> script or need non-FAT32 partitions, you can manually create a customizable boot device by manually copying Alpine Linux Files and install the bootloader to make the device bootable. | |||
=== 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). | |||
# 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 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): | |||
#: {{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>}} | |||
=== 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 == | |||
=== 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 === | |||
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]] | |||
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.) | |||
=== 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 == | |||
* [[Alpine_Linux_package_management#Local_Cache|APK Local Cache]] | |||
* [[Alpine local backup]] | |||
* [[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs|update-kernel script]] | |||
[[Category:Installation]] |
Latest revision as of 04:36, 24 October 2024
This page is about creating customizable boot devices for diskless or data disk-mode Alpine Linux using a writable filesystem i.e. not iso9660, so that local customizations like apkovl files and cached packages can be stored. It allows to also 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.
- A customizable boot device that can be a USB-Stick/CompactFlash/SDCard etc., or harddisk partition for the diskless or data mode Alpine linux.
Using setup-bootable
setup-bootable script is the preferred method to create a directly customizable bootable device on a FAT32 filesystem. For other filesystems refer Manually copying Alpine files.
Complete the Installation until the base configuration step by booting from an Alpine Linux Installation Media. 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
Run lsblk
to figure out what the disk to turn into your bootable device. Let's say it's /dev/sda for this example, change as needed:
# 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. Alter the device name i.e/dev/sda1 as needed.
mkfs.vfat /dev/sda1
Figure out where your install media files are mounted. if you run a df
command, you should see a read only 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
After that's done, remove Installation Media and reboot the system.
Once the system boots from the customizable boot device /dev/sda1, login as root and run setup-alpine
once again to complete the Installation until the base configuration step.
# setup-alpine ... 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]:
For the question on disk to use, select none. The script will then ask about storing configs. Choose the customizable boot device.('sda1' in this example). Then the script will ask you for apk cache directory, accept the default or type as follows i.e /media/sda1/cache. Refer APK Local Cache for more details.
Always remember to run lbu ci
to commit the above changes to disk.
# lbu ci
Test/verify by rebooting and seeing that your alpine setup is preserved in the customizable boot device.
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 and install the bootloader to make the device bootable.
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).
- 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
- 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
- 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 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
- (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
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
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
. See: Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs
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.