Setting up disks manually: Difference between revisions

From Alpine Linux
(fixed grammar, typos etc..)
 
(67 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Alpine Linux modes ==
System Disk Mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[:Category:Desktop|desktop]], development machines etc.  
Alpine Linux can be installed and run in following three modes.  


==='''Diskless Mode'''===
If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.
In Diskless mode the entire operating system with all applications are first loaded into RAM and then only run from there. This is the method already used to boot the .iso installation images, however <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> can also configure the installed system to continue to boot like this if "disk=none" is specified. The mode is extremely fast and can save on unnecessary disk spin-ups, power, and wear. It is similar to what other linux distributions may call a "frugal" install or boot into with a "toram" option.  


Custom configurations and package installations may optionally still be preserved or "persist" across reboots by using the Alpine local backup tool <code>[[Alpine_local_backup|lbu]]</code>. It enables committing and reverting system states by using .apkovl files that are saved to writable storage and loaded when booting. If additional or updated packages have been added to the system, these may also be made available for automatic (re)installation during the boot phase without any (re)downloading, by enabling a [[Alpine_Package_Keeper#Local_Cache|local package cache]] on the writable storage.
== setup-disk based Installation ==


[[https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10473 FIXME-1]: Storing local configs and the package cache on '''internal disks still require''' [[Alpine_local_backup#Saving_and_loading_ISO_image_customizations|some manual steps]] to have the partition listed, i.e. making a /etc/fstab entry, mountpoint, and mount, *before* running setup-alpine. The linked workaround also still requires to commit these configurations to disk manually before rebooting.]
To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.


If a writable partition is available, <code>setup-alpine</code> can be told to store the configs and the package cache on that writable partition. (Later, another directory on that same partition or another available partition may also be mounted as /home, or for example, for selected important applications to keep their run-time and user data on it.)
# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[#Creating_partitions|create]] them first and [[#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)'''  partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Filesystems#Swap_Partition|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.


The boot device of the newly configured local "diskless" system may remain the initial (and possibly read-only) installation media. But it is also possible to copy the boot system to a partition (e.g. /dev/sdXY) with <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code>.
== Manual partitioning ==


==='''Data Disk Mode'''===
=== Partitioning tools ===
In Data Disk mode also the operating system runs from system RAM, thus it enjoys the same accelerated operation speed as "diskless" mode. However, swap storage and the entire {{Path|/var}} directory tree get mounted from a persistent storage device (two newly created partitions). The directory {{Path|/var}} holds e.g. all log files, mailspools, databases, etc., as well as <code>[[Alpine_local_backup|lbu]]</code> backup commits and the package cache. This mode is useful for having RAM accelerated servers with variable amounts of user-data that exceed the available RAM size. It enables the entire current system state (not just the boot state) to survive a system crash in accordance with the particular filesystem guarantees.


[[https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10474 FIXME-2]]: Setup-alpine will create the data partition and mount it as /var, but '''setup-alpine's "data" disk mode can not yet configure lbu config storage settings automatically'''. The '''current workaround''', is to select "none" at the 'where to store configs' prompt (as the new data partition is not listed anyway) and configure lbu manually after <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> exits, and before rebooting:
The installation image enviroment may have only the very basic busybox built-in <code>fdisk</code> command available. Busybox <code>fdisk</code> is rather limited for edit operations (e.g.: it can read but not modify GPT). Instead, alpine allows you to install more complete partitioning tool packages:


# Identify the created data partition, e.g. <code>/dev/sd''XY''</code>, and its filesystemtype, e.g. using <code>''lsblk''</code>
*
# Manually edit the lbu backups location in <code>/etc/lbu/lbu.conf</code> and configure <code>LBU_MEDIA=sd''XY''</code> (according to the previous findings).
{| class="wikitable"
# Save the configuration on that partition for the next boot with <code>lbu commit</code>.
|+ Partitioning tools
# If (a new) partition fails to get mounted, execute: <code>mkdir /media/''sdXY'' ; echo "/dev/sd''XY'' /media/sd''XY'' ''fstype'' noauto,rw 0 0" >> /etc/fstab</code>, and try <code>lbu commit</code> again.
|-
! Command !! Package name !! Features !! Limitations
|-
| fdisk || Inbuilt {{pkg|busybox}} || can read GPT, Modify MBR || Cannot modify GPT
|-
| gdisk || {{pkg|gptfdisk}} || text mode, supports MBR/GPT bidirectional conversion, best for managing GPT partition tables|| None
|-
| cgdisk  || {{pkg|gptfdisk}}  || menu driven curses interface for gdisk || None
|-
| sgdisk || {{pkg|sgdisk}} || scriptable gdisk || Non-interactive
|-
| fdisk || {{pkg|util-linux-misc}} || text mode, supports both gpt and MBR, best for managing MBR partition tables || None except size due to other tools
|-
| cfdisk || {{pkg|cfdisk}} || menu driven curses interface for fdisk || None
|-
| sfdisk || {{pkg|sfdisk}} || scriptable fdisk || Non-interactive
|-
| parted || {{pkg|parted}} || text mode, supports both gpt and MBR|| cannot convert MBR to GPT, different interface from above tools
|}


In data disk mode, the boot device may also remain the initial (and possibly read-only) installation media, or be copied to a partition (e.g. /dev/sdXY) with <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code>.
All the above tools can be installed during [[Installation]] immediately after setting up [[Installation#Base_configuration|base configuration]].
Graphical tools like {{pkg|gparted}} and {{pkg|gnome-disk-utility}} can be used only after [[Installation#Post-Installation|setting up a graphical environment]].


==='''System Disk Mode'''===
=== Creating partitions ===


System Disk Mode is the traditional hard-disk install. If this mode is selected, the <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> script deletes the existing partitions and creates three partitions on the selected storage device, {{Path|/boot}}, {{Path|swap}} and {{Path|/}} (the filesystem root). This mode may, for example, be used for generic [[:Category:Desktop|desktop]] and development machines.
For Alpine Linux, only the '''(/)'''root partition is mandatory. Even  a '''/boot''' partition and  '''swap''' are optional.


Refer [[#Custom partitioning of the harddisk]], if you do not want to use entire disk for Alpine Linux.
{{Warning|Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.}}
The menu choices that are provided by <code>setup-alpine</code> might not cover all needs, however, it's possible to:
<code>cfdisk</code> will be used in all examples here as it is based on text menu without any dependencies. However, installing the package {{Pkg|<code>cfdisk</code>}} requires network to be available if using Standard ISO boot image.
<code>cgdisk</code> is also recommended for its excellent support for GPT partitions and conversion from MBR to GPT.


* Call [[Alpine_setup_scripts#setup-disk|setup-disk]] directly, instead of through <code>setup-alpine</code>, and pass some specific partitioning parameters to it.
Alternately, {{Pkg|<code>sfdisk</code>}} is available in Standard ISO boot image and can be installed without network.
* Set up the partitions and filesystems manually (to the desired details) and [[Alpine_setup_scripts#Partitioning|tell setup-disk]] to install to the prepared target mountpoint.


(Beta reference: [https://docs.alpinelinux.org/user-handbook/0.1a/Installing/manual.html#_finalizing docs.alpinelinux.org] )
The following step installs the package {{Pkg|<code>cfdisk</code>}}:  
{{cmd|# apk add cfdisk }}


== Using setup-disk features ==
<code>cfdisk</code> will be used to create partitions. Before using <code>cfdisk</code>, the disk name must be identified by using <code>blkid</code>:


{{Draft|Some information on this page may be incomplete or outdate.}}
{{cmd|# blkid}}
<pre>
/dev/sdX1: LABEL="some" UUID="..." TYPE="vfat"
/dev/sdX2: LABEL="other" UUID="..." TYPE="ext4"
</pre>


=== For "diskless" and "data" disk mode installs ===
When <code>cfdisk</code> is run as follows, it looks for existing partitions on the disk {{Path|/dev/sdX}} :
{{cmd|# cfdisk /dev/sdX}}


This requires some manual steps, as long as the setup-scripts auto-detect usable partitions only on '''removable''' devices (not internal harddisks). They do not support creating new, writable partitions to be used by Alpine.
=== Resizing an existing partition ===
{{Warning|Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.}}


How to prepare writable storage space is explained in the section [[Setting_up_disks_manually#Manual_partitioning| manual partitioning]], below.
<code>cfdisk</code> and <code>resize2fs</code> can be used to resize existing partitions of ext2/3/4 filsystem on the disk. For other filsystems, the necessary [[Filesystems#Filesystem_Tools|filesystem tools]] must be installed. This can be done while booted.  


* Be aware of this Bug: {{Issue|11589|The APKOVL loading of diskless setups doesn't work on btrfs and xfs filesystems, or nvme-based devices}} => So, for the moment, use only ext4 filesystem partitions on classic drives to store diskless mode states.
[[File:Cfdisk screenshot alpine 2024-03-04 143916.png|thumb|cfdisk screenshot ]]


The following creates an ext4 partition with disabled journaling, to reduce write operations and allow the disk to spin down after the .apkovl and the packages have been read from the partition during the boot.
To resize disk, launch the <code>cfdisk</code>:
{{cmd|# cfdisk {{path|/dev/sda}}}}


# mkfs.ext4 -O ^has_journal /dev/sdXY  # the "-O ^has_journal" DISABLES journaling ("^" means "not")
# Select the target partition, here as per image {{path|/dev/sda3}}
# Select ''Resize'' from the bottom menu.
# Enter the new ''Size'' at the prompt.
# Select ''Write'', then ''Quit''


{{Note|IMPORTANT! There may be additional steps necessary to make proper use of the partition, see
If a filesystem is resized with -f (online mode), then the system must be rebooted immediately after the change is made.
[[Alpine_local_backup#Saving_and_loading_ISO_image_customizations|Saving and loading ISO image customizations]].
}}


{{Note| mkfs.ext4 creates ext4 fs with 64bit feature enabled by default, but extlinux may not be able to boot with that, see Issue {{Issue|14895}}. You may need to add "-O ^has_journal,^64bit" to mkfs.ext4 to circumvent this.
{{cmd|# resize2fs -f {{path|/dev/sda3}}
}}
&num; reboot}}
 
 
=== System disk mode Installation ===


<code>setup-disk</code> is used to [[Installation#System_Disk_mode_Install|Install]] alpine on harddisk by the <code>setup-alpine</code> script.
=== Formatting partitions ===


{{Cmd|setup-disk /dev/sdX}}
{{Warning|The {{Path|/dev/sdXY}} is only an example. Make sure you use the right partition name/number. Use <code>blkid</code> command to verify the partition name/number. Choosing the wrong partition leads to data loss. If you are unsure, do not proceed, seek [[Alpine Linux:Support|support]].}}


If DISKDEV i.e device name like /dev/sdX or /dev/nvme0n1 is specified, then <code>setup-disk</code> will use the specified disk(s) to Install alpine without asking. If
Whenever a partition is [[#Creating_partitions|created]], the partition must be formatted first before using it.  Depending on the filesystem to be used, the necessary [[Filesystems#Filesystem_Tools|formatting tool]] for the filesystem must be installed first.
multiple disks are specified then set them up in a RAID array. If there are
{{:Filesystems}}
more than 2 disks, then use raid level 5 instead of raid level 1. Refer [[#RAID|RAID]] for more options.


<code>setup-disk</code> will by default set up a root partition, a separate /boot partition and a swap partition on the given DISKDEV. This is the layout used in [[Installation#System_Disk_mode_Install]] by <code>setup-alpine</code> script.  
Install the [[Filesystems#Filesystem_Tools|filesystem tools]] first, if not done already. The following examples show how to use the formatting tools for different filesystems:


If MOUNTPOINT is specified, then <code>setup-disk</code> will do a traditional disk install with MOUNTPOINT as root. If you want a different layout or a different filesystem or you want to install OS in an existing partition, you must manually create the partitions, filesystems and mount them on {{Path|/mnt}} (or any other mount point):
* e2fsprogs for ext4,ext3 and ext2. ext4 is the default filesystem in Alpine Linux: {{Cmd|# mkfs.ext4 /dev/sdaXY}}
* btrfs-progs for [[btrfs]] filesystem. {{Cmd|# mkfs.btrfs /dev/sdaXY}}
* dosfstools for fat12/fat16/fat32 filesystem. This is also used for [[UEFI|EFI]] system partition(ESP). {{Cmd|# mkfs.vfat /dev/sdaXY}}
* f2fs-tools for [[F2FS]] filesystem. {{Cmd|# mkfs.f2fs /dev/sdaXY}}


{{Cmd|# mount /dev/sdXY /mnt}}
== Disk layouts ==


If you're using EFI, make sure you create a mount point <code>/mnt/boot/efi</code> and
{{Draft|This entire section including RAID, Encryption and LVM needs to be updated.}}
 
{{Cmd|# mkdir -p /mnt/boot/efi}}
 
Find the correct partition name for <code>esp</code> partition and mount it on the above mount point :
 
{{Cmd|# mount /dev/esp /mnt/boot/efi}}
 
Then install Alpine Linux using the following command:
{{Cmd|# setup-disk -m sys /mnt}}
 
<code>setup-disk</code> will install a Alpine Linux system on the mounted root, detect your file system layout and generate an fstab and also install a suitable boot loader.
 
<!--
 
To be arranged properly
 
If you're using the MBR, you are responsible for making the proper partition bootable and make sure the MBR is OK for extlinux. and set <code>BOOTLOADER=grub</code> and <code>USE_EFI=1</code>, and that {{Pkg|grub-efi}} and {{Pkg|efibootmgr}} are installed before running <code>setup-disk</code>. If your system still does not boot, you can try to manually create a boot entry with {{Pkg|efibootmgr}}, for which instructions can be found at [https://wiki.alpinelinux.org/wiki/Bootloaders#efibootmgr EFI Boot Stub].
-->
See also [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]
 
==== Dual-booting ====
See [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
 
==== Other needs ====
* [[Installing Alpine Linux in a chroot]]
* [[Replacing non-Alpine Linux with Alpine remotely]]
 
==== Disk layouts ====


It is possible to have one or more of RAID, encrypted, and/or Logical Volume on your {{Path|/}} (root) volume. However, the Alpine init script only knows how to handle them when they're layered in that order, and your initram and extlinux.conf files in the {{Path|/boot}} partition are configured properly.
It is possible to have one or more of RAID, encrypted, and/or Logical Volume on your {{Path|/}} (root) volume. However, the Alpine init script only knows how to handle them when they're layered in that order, and your initram and extlinux.conf files in the {{Path|/boot}} partition are configured properly.
Line 158: Line 162:
In a three-disk system, the {{Path|/boot}} would still be RAID1, but the larger partition might, in that case, be RAID5.
In a three-disk system, the {{Path|/boot}} would still be RAID1, but the larger partition might, in that case, be RAID5.


==== RAID ====
=== RAID ===


<code>setup-disk</code> will automatically build a RAID array if you supply the '''-r''' switch, or if you specify more than one device.
<code>setup-disk</code> will automatically build a RAID array if you supply the '''-r''' switch, or if you specify more than one device.
Line 181: Line 185:
You might also need to manually tweak {{Path|$MNT/etc/fstab}}. And you might need to copy {{Path|/usr/share/syslinux/mbr.bin}} to your disk's MBR.
You might also need to manually tweak {{Path|$MNT/etc/fstab}}. And you might need to copy {{Path|/usr/share/syslinux/mbr.bin}} to your disk's MBR.


==== Encryption ====
=== Encryption ===


See [[Setting up encrypted volumes with LUKS]]. You can add an additional Logical Volume layer, or just unlock the volume you've created (using <code>cryptsetup luksOpen ...</code>), and supply the {{Path|/dev/mapper/<i>something</i>}} device directly to [[setup-disk]]. When you're finished, be sure to relock the volume (using <code>cryptsetup luksClose ...</code>) before rebooting.
See [[Setting up encrypted volumes with LUKS]]. You can add an additional Logical Volume layer, or just unlock the volume you've created (using <code>cryptsetup luksOpen ...</code>), and supply the {{Path|/dev/mapper/<i>something</i>}} device directly to [[setup-disk]]. When you're finished, be sure to relock the volume (using <code>cryptsetup luksClose ...</code>) before rebooting.
Line 200: Line 204:
You might also need to manually tweak {{Path|$MNT/etc/fstab}}.
You might also need to manually tweak {{Path|$MNT/etc/fstab}}.


==== LVM ====
=== LVM ===


<code>setup-disk</code> will automatically build and use volumes in a LVM group if you supply the '''-L''' switch.
<code>setup-disk</code> will automatically build and use volumes in a LVM group if you supply the '''-L''' switch.
Line 223: Line 227:
You might also need to manually tweak {{Path|$MNT/etc/fstab}}.
You might also need to manually tweak {{Path|$MNT/etc/fstab}}.


== Manual partitioning ==
== Troubleshooting ==
 
=== Partitioning tools ===
The installation image enviroment may have only the very basic busybox built-in <code>fdisk</code> command available. However, alpine allows you to install more complete partitioning tool packages like <code>sfdisk</code> (scriptable fdisk), <code>gptfdisk</code>, <code>parted</code> (CLI), <code>cfdisk</code> (text menus), or even <code>gparted</code> (after [[Installation#Post-Installation|setting up a graphical environment]]).
 
The following steps installs <code>cfdisk</code>, looks for existing partitions, and runs cfdisk against <code>/dev/sdX</code>:
{{cmd|# apk add cfdisk e2fsprogs}}
{{cmd|# blkid}}
<pre>
/dev/sdX1: LABEL="some" UUID="..." TYPE="vfat"
/dev/sdX2: LABEL="other" UUID="..." TYPE="ext4"
</pre>
{{cmd|# cfdisk /dev/sdX}}
 


<!--
=== Mounting on /dev/sdXY sysroot failed ===
Create partition with with type "Linux" (83).
apk_add e2fsprogs rsync
mkfs.ext3 /dev/hda1
mount -t ext3 /dev/hda1 /mnt
ROOT=/mnt apk_add uclibc busybox apk-tools alpine-baselayout alpine-conf
# Install busybox links
mkdir /mnt/proc && mount --bind /proc /mnt/proc && chroot /mnt /bin/busybox --install -s && umount /mnt/proc
# Copy the apk repository
rsync -ruav /media/cdrom/apks /mnt
mkdir /mnt/etc/apk && echo "APK_PATH=file://apks" > /mnt/etc/apk/apk.conf
# Copy the hd/ext3 initramfs image, kernel and kernel modules
rsync -ruav /media/cdrom/kernel/generic/hd-ext3.gz /media/cdrom/kernel/generic/bzImage /mnt
rsync -ruav /lib/modules/* /mnt/lib/modules/
-->


<!--
The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:
=== Setting up RAID ===
Set up a raid array as described [[Setting up a software RAID1 array|here]].
In this document, two raid arrays are configured: md0 for swap (512MB) and md1 for /var.


=== Create filesystem ===
<Pre>
We need to install the software to create the filesystem ("format" the partition).
mounting /dev/sda8 on /sysroot failed: No such file or directory
apk_add e2fsprogs
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>


If you use an Alpine release older than 1.3.8 you will need to manually create a link to /etc/mtab.
The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.
ln -fs /proc/mounts /etc/mtab


Create the filesystem. The -j option makes it ext'''3'''. Without the -j option it will become non-journaling ext'''2'''. This step might take some time if your partition is big.
# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
mke2fs -j /dev/md1
# Ensure that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If the error message matched in step 4, check whether filesystem modules are loaded by issuing the command. {{Cmd|<nowiki>lsmod |grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].


==== Missing filesystem modules in the kernel cmdline ====


Now edit /etc/fstab and add your new partitions. Mine looks like this:
[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.
none            /proc          proc    defaults 0 0
none            /sys            sysfs  defaults 0 0
udev            /dev            tmpfs  size=100k 0 0
none            /dev/pts        devpts  defaults 0 0
tmpfs          /dev/shm        tmpfs  defaults 0 0
/dev/cdrom      /media/cdrom    iso9660 ro 0 0
/dev/fd0        /media/floppy  vfat    noauto  0 0
/dev/usba1      /media/usb      vfat    noauto  0 0
none            /proc/bus/usb  usbfs noauto 0 0
 
/dev/md0        swap            swap    defaults 0 0
/dev/md1        /var            ext3    defaults 0 0


=== Move the data ===
# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
Stop aall services running that put anything in /var (syslog for example). If you have booted on a clean installation and not run setup-alpine, then no services should be running. However, some packages might have created dirs in /var, so we need to backup /var, mount the new /var directory and move all backed up dirs to the raided /var.
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}


mv /var /var.tmp
Choose the appropriate solution based on your use case for a permanent fix:
mkdir /var
mount /var
mv /var.tmp/* /var
rmdir /var.tmp


Verify that everyting looks ok with the ''df'' utility.
*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
~ $ df
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
Filesystem          1k-blocks      Used Available Use% Mounted on
...</nowiki>}}
none                    255172    23544    231628  9% /
udev                      100        0      100  0% /dev
/dev/cdrom              142276    142276        0 100% /media/cdrom
/dev/md1              37977060    181056  35866876  1% /var


=== Survive reboots ===
*If you are using [[Bootloaders#Syslinux|Syslinux]], then ensure that {{Codeline|APPEND root}} line in the file {{Path|/boot/extlinux.conf}} has the appropriate filesystem module <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
Now we have everything up and running. We need to make sure that everything will be restored during next reboot.
APPEND root=/dev/sdXY modules=sd-load,usb-storage,ext4 quiet
...</nowiki>}}


Create an initscript that will mount /var for you during boot. I call it /etc/init.d/mountdisk and it looks like this:
{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}
#!/sbin/runscript
   
   
start() {
*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.
        ebegin "Mounting /var"
        mount /var
        eend $?
}
stop() {
        ebegin "Unmounting /var"
        umount /var
        eend $?
}


Make it exectutable:
== See also ==
chmod +x /etc/init.d/mountdisk
* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
 
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
'''NOTE:''' Since Alpine-1.7.3 a script named ''localmount'' is included so you will not need to create your own ''mountdisk'' script.
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
 
* [[Replacing non-Alpine Linux with Alpine remotely]]
/var needs to be mounted *after* raid is created. The -k option will make alpine unmount the /var partition during boot. Add start swap to boot:
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]
rc_add -k -s 06 mountdisk
* [https://www.rodsbooks.com/gdisk/index.html Gdisk official website] '' walkthroughs available for gdisk,cgdisk and sgdisk''
rc_add -k -s 06 swap
 
The /dev/md* device nodes will not be created automatically, so we need to put them on floppy too.
lbu include /dev/md*
 
If you have users on the server and want /home to be permanent, you can create a directory /var/home and create links to /var/home.
mkdir /var/home
mv /home/* /var/home/
ln -s /var/home/* /home/
 
'''NOTE:''' You cannot just replace /home with a link that points to /var/home since the base has a /home directory. When the system tries to copy the config from floppy it will fail because of the already existing /home directory.
 
Make sure the links are stored to floppy:
lbu include /home/*
 
Also remember to move any newly created users to /var/home and create a link:
adduser bob
mv /home/bob /var/home/
ln -s /var/home/bob /home/bob
lbu include /home/bob
 
Save to floppy:
lbu commit floppy
 
=== Operational Test ===
Reboot computer. Now the raid should start and /var should be mounted. Check with df:
~ $ df
Filesystem          1k-blocks      Used Available Use% Mounted on
none                    255172    23976    231196  9% /
mdev                      100        0      100  0% /dev
/dev/cdrom              140932    140932        0 100% /media/cdrom
/dev/md1              37977060    180984  35866948  1% /var
 
=== Upgrades ===
Since the package database is on disk, you cannot update by simply replacing the CDROM. You will have to either run the upgrade on the new CDROM or run ''apk_add -u ... && update-conf'' manually.
-->
 
=== Setting up swap ===
 
# create a partition with the type set to "linux swap" (82) (If you're going to use a logical volume for swap, skip this step and <code>lvcreate</code> that instead.)
# <code>mkswap /dev/sda2</code>
# <code>echo -e "/dev/sda2 none swap sw 0 0" >> /mnt/etc/fstab</code>
# <code>swapon /dev/sda2</code> (or <code>rc-service swap start</code>)
 
{{Cmd|free -m}} will show how much swap space is available (in MB).
 
If you prefer maximum speed, you don't need configure any raid devices for swap. Just add 2 swap partitions on different disks and linux will stripe them automatically. The downside is that the moment one disk fails, the system will go down. For better reliability, put swap on RAID1.
 
{{Todo|Instructions for cryptswap?}}
 
=== Custom boot partition size ===
 
The default boot partition size is under 40MB. This can cause errors if package updates require additional space on {{path|/boot}}.
Executing {{ic|export BOOT_SIZE{{=}}512}} before running {{ic|setup-disk}} will result in a 512MB boot partition.
 
== Expanding an existing disk ==
Unlike gnu `fdisk`, busybox `fdisk` is rather limited in edit operations.  Instead, use `cfdisk` and `resize2fs` to resize the disk.  This can be done while booted.
 
Install tools:
[[File:Cfdisk screenshot alpine 2024-03-04 143916.png|thumb|cfdisk screenshot ]]
{{cmd|# apk add {{pkg|cfdisk|arch=}} {{pkg|e2fsprogs-extra|arch=}}}}
resize disk
{{cmd|# cfdisk {{path|/dev/sda}}}}
 
# Select the target partition, often {{path|/dev/sda3}}
# Select ''Resize'' from the bottom menu
# Select ''Write'', then ''Quit''
 
resize filesystem with -f (online mode), then reboot
{{cmd|# resize2fs -f {{path|/dev/sda3}}
&num; reboot}}


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

Latest revision as of 09:01, 14 January 2025

System Disk Mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic desktop, development machines etc.

If an entire hard disk(s) is available for Alpine Linux, setup-alpine based install is the recommended way to install Alpine Linux. For all other use cases, follow the setup-disk based Installation given below.

setup-disk based Installation

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT /mnt as root and run the command setup-disk -m sys /mnt.

  1. Follow the Installation guide to complete the base configuration, if not already done. A working Internet access is mandatory to complete this installation.
  2. If necessary formatted partition(s) are unavailable, manually create them first and format them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for extlinux.
  3. Mount the / (root) partition on a mount point i.e say /mnt as follows:

    # mount /dev/sdXY /mnt

  4. If you're using EFI, create a mount point /mnt/boot and mount the EFI system partition(ESP) on it.

    # mkdir -p /mnt/boot # mount /dev/sdXY /mnt/boot

  5. If swap partition is available, you can also enable it now:

    # swapon /dev/sdXY

  6. Install Alpine Linux using the following command:

    # setup-disk -m sys /mnt

  7. setup-disk will perform a traditional hard disk install of your running system, detects your file system layout and generates /etc/fstab and installs a bootloader based on the BOOTLOADER environment variable.
  8. At the end of Installation, you can reboot to boot into the newly installed Alpine Linux and configure further.

Manual partitioning

Partitioning tools

The installation image enviroment may have only the very basic busybox built-in fdisk command available. Busybox fdisk is rather limited for edit operations (e.g.: it can read but not modify GPT). Instead, alpine allows you to install more complete partitioning tool packages:

Partitioning tools
Command Package name Features Limitations
fdisk Inbuilt busybox can read GPT, Modify MBR Cannot modify GPT
gdisk gptfdisk text mode, supports MBR/GPT bidirectional conversion, best for managing GPT partition tables None
cgdisk gptfdisk menu driven curses interface for gdisk None
sgdisk sgdisk scriptable gdisk Non-interactive
fdisk util-linux-misc text mode, supports both gpt and MBR, best for managing MBR partition tables None except size due to other tools
cfdisk cfdisk menu driven curses interface for fdisk None
sfdisk sfdisk scriptable fdisk Non-interactive
parted parted text mode, supports both gpt and MBR cannot convert MBR to GPT, different interface from above tools

All the above tools can be installed during Installation immediately after setting up base configuration. Graphical tools like gparted and gnome-disk-utility can be used only after setting up a graphical environment.

Creating partitions

For Alpine Linux, only the (/)root partition is mandatory. Even a /boot partition and swap are optional.

Warning: Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.


cfdisk will be used in all examples here as it is based on text menu without any dependencies. However, installing the package cfdisk requires network to be available if using Standard ISO boot image. cgdisk is also recommended for its excellent support for GPT partitions and conversion from MBR to GPT.

Alternately, sfdisk is available in Standard ISO boot image and can be installed without network.

The following step installs the package cfdisk:

# apk add cfdisk

cfdisk will be used to create partitions. Before using cfdisk, the disk name must be identified by using blkid:

# blkid

/dev/sdX1: LABEL="some" UUID="..." TYPE="vfat"
/dev/sdX2: LABEL="other" UUID="..." TYPE="ext4"

When cfdisk is run as follows, it looks for existing partitions on the disk /dev/sdX :

# cfdisk /dev/sdX

Resizing an existing partition

Warning: Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.


cfdisk and resize2fs can be used to resize existing partitions of ext2/3/4 filsystem on the disk. For other filsystems, the necessary filesystem tools must be installed. This can be done while booted.

cfdisk screenshot

To resize disk, launch the cfdisk:

# cfdisk /dev/sda

  1. Select the target partition, here as per image /dev/sda3
  2. Select Resize from the bottom menu.
  3. Enter the new Size at the prompt.
  4. Select Write, then Quit

If a filesystem is resized with -f (online mode), then the system must be rebooted immediately after the change is made.

# resize2fs -f /dev/sda3 # reboot

Formatting partitions

Warning: The /dev/sdXY is only an example. Make sure you use the right partition name/number. Use blkid command to verify the partition name/number. Choosing the wrong partition leads to data loss. If you are unsure, do not proceed, seek support.


Whenever a partition is created, the partition must be formatted first before using it. Depending on the filesystem to be used, the necessary formatting tool for the filesystem must be installed first.

Tool Filesystem Brief Notes Formatting command
btrfs-progs Btrfs mkfs.btrfs
dosfstools FAT12/FAT16/FAT32 used for EFI partition mkfs.vfat
e2fsprogs ext2/ext3/ext4 ext4 is current default in Linux mkfs.ext4
f2fs-tools F2FS
hfsprogs XFS HFS/HFS+ Apple/Mac products
jfsutils JFS
ntfs-3g NTFS Microsoft/Windows FUSE driver
xfsprogs XFS


Install the filesystem tools first, if not done already. The following examples show how to use the formatting tools for different filesystems:

  • e2fsprogs for ext4,ext3 and ext2. ext4 is the default filesystem in Alpine Linux:

    # mkfs.ext4 /dev/sdaXY

  • btrfs-progs for btrfs filesystem.

    # mkfs.btrfs /dev/sdaXY

  • dosfstools for fat12/fat16/fat32 filesystem. This is also used for EFI system partition(ESP).

    # mkfs.vfat /dev/sdaXY

  • f2fs-tools for F2FS filesystem.

    # mkfs.f2fs /dev/sdaXY

Disk layouts

This material is work-in-progress ...

This entire section including RAID, Encryption and LVM needs to be updated.
(Last edited by Prabuanand on 14 Jan 2025.)

It is possible to have one or more of RAID, encrypted, and/or Logical Volume on your / (root) volume. However, the Alpine init script only knows how to handle them when they're layered in that order, and your initram and extlinux.conf files in the /boot partition are configured properly.

Your /boot directory cannot reside on an encrypted or LVM volume, at least not with Alpine's default bootloader (extlinux). (Grub2 can deal with /boot being on an LVM volume.) The usual practice is to create a small partition for /boot, then devote the rest of your disk to a separate partition on which you layer one or more of RAID, encryption, and/or Logical Volumes.

Sometimes /boot is also set up as a mirrored (RAID1) volume. However, this is just for post-init access. That way, when you write a new kernel or bootloader config file to /boot, it gets written to multiple physical partitions. During the pre-init, bootloader phase, only one of those partitions will be read from.

A typical setup might look like this: 

One-disk system
---------------
  +------------------------------------------------+
  |  small partition (32--100M), holding           |
  |  only /boot, filesystem needn't be journaled   |
  +------------------------------------------------+
  |  rest of disk in second partition              |
  |  +------------------------------------------+  |
  |  | cryptsetup volume                        |  |
  |  |  +-------------------------------------+ |  |
  |  |  |  LVM PV, containing single VG,      | |  |
  |  |  |  containing multiple LVs, holding   | |  |
  |  |  |  /, /home, swap, etc                | |  |
  |  |  +-------------------------------------+ |  |
  |  +------------------------------------------+  |
  +------------------------------------------------+


Two-disk system
---------------
  +------------------------------------------------+  +------------------------------------------------+
  |  small partition (32--100M), holding           |  |  small partition (32--100M), holding           | These 2 partitions might
  |  only /boot, filesystem needn't be journaled   |  |  only /boot, filesystem needn't be journaled   | form a mirrored (RAID1)
  +------------------------------------------------+  +------------------------------------------------+ volume
  |  rest of disk in second partition              |  |  rest of disk in second partition              |
  | T================================================================================================T | These 2 partitions form
  | T +--------------------------------------------------------------------------------------------+ T | a second mirrored
  | T | cryptsetup volume                                                                          | T | (RAID1) volume
  | T |  +---------------------------------------------------------------------------------------+ | T |
  | T |  | LVM PV, containing single VG,                                                         | | T |
  | T |  | containing multiple LVs, holding                                                      | | T |
  | T |  | /, /home, swap, etc                                                                   | | T |
  | T |  +---------------------------------------------------------------------------------------+ | T |
  | T +--------------------------------------------------------------------------------------------+ T |
  | T================================================================================================T |
  |                                                |  |                                                |
  +------------------------------------------------+  +------------------------------------------------+

In a three-disk system, the /boot would still be RAID1, but the larger partition might, in that case, be RAID5.

RAID

setup-disk will automatically build a RAID array if you supply the -r switch, or if you specify more than one device.

If you want to build your RAID array manually, see Setting up a software RAID array. Then you can add additional layers of encryption and/or Logical Volumes, or just assemble the RAID array, and supply the /dev/mdi device directly to setup-disk. When you're finished, be sure to disassemble the RAID array before rebooting.

If setup-disk sees that you're using RAID, either because you gave it the -r switch, or multiple devices, or a /dev/mdi device, then it will set up your initramfs and extlinux.conf file properly. However, in other cases, such as when you're also using encryption, or you invoke setup-disk with a mounted directory argument, these might not be properly set up for RAID. In that case, you may need to manually edit/rebuild them. The following assumes that $MNT holds the root directory you're installing into:

echo "/sbin/mdadm" > $MNT/etc/mkinitfs/files.d/raid echo "/etc/mdadm.conf" >> $MNT/etc/mkinitfs/files.d/raid # edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..." # includes raid (this field is space-separated and quoted) mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT # edit $MNT/etc/update-extlinux.conf to make sure modules=... contains # raid1 or raid456 (whichever your / is on; this field is comma-separated) # also check the root= setting extlinux --raid --install $MNT/boot --update

Todo: Does adding the --update option to extlinux ... suffice to make /boot/extlinux.conf be regenerated? Or do we need to manually tweak that file, or run update-extlinux, as well?


You might also need to manually tweak $MNT/etc/fstab. And you might need to copy /usr/share/syslinux/mbr.bin to your disk's MBR.

Encryption

See Setting up encrypted volumes with LUKS. You can add an additional Logical Volume layer, or just unlock the volume you've created (using cryptsetup luksOpen ...), and supply the /dev/mapper/something device directly to setup-disk. When you're finished, be sure to relock the volume (using cryptsetup luksClose ...) before rebooting.

If you install your / (root) on an encrypted volume, you'll need to manually edit/rebuild your initram and your extlinux.conf file. The following assumes that $MNT holds the root directory you're installing into, that you've created the cryptvolume on the device /dev/md2, and that you want to unlock the encrypted volume into a virtual volume named "crypt":

# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..." # includes cryptsetup (this field is space-separated and quoted) mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT # edit $MNT/etc/update-extlinux.conf to make sure default_kernel_opts="..." # contains cryptroot=/dev/md1 and cryptdm=crypt (this field is also space-separated and quoted) # also check the root= setting extlinux --install $MNT/boot --update

Todo: Does adding the --update option to extlinux ... suffice to make /boot/extlinux.conf be regenerated? Or do we need to manually tweak that file, or run update-extlinux, as well?


You might also need to manually tweak $MNT/etc/fstab.

LVM

setup-disk will automatically build and use volumes in a LVM group if you supply the -L switch.

If you instead want to build your LVM system manually, see Setting up Logical Volumes with LVM. Then vgchange -ay, format and mount your volumes, and supply the root mountpoint to setup-disk. When you're finished, be sure to

umount ... vgchange -an

before rebooting.


If setup-disk sees that you're using LVM, perhaps because you gave it the -L switch, then it will set up your initram and extlinux.conf file properly. However, in other cases, these might not be properly set up. In that case, you may need to manually edit/rebuild them. The following assumes that $MNT holds the root directory you're installing into:

# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..." # includes lvm (this field is space-separated and quoted) mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT # edit $MNT/etc/update-extlinux.conf to make sure root= is set correctly extlinux --install $MNT/boot --update

Todo: Does adding the --update option to extlinux ... suffice to make /boot/extlinux.conf be regenerated? Or do we need to manually tweak that file, or run update-extlinux, as well?


You might also need to manually tweak $MNT/etc/fstab.

Troubleshooting

Mounting on /dev/sdXY sysroot failed

The error message appears as follows with variations in /dev/sda8 depending on the partition number and SSD/HDD etc: 

mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

  1. Verify that the partition name in which Alpine Linux was installed matches the above error by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") :

    blkid

  2. Ensure that sysroot exists by issuing the command.

    ls -ld /sysroot

  3. Check if the above error message apears when issuing the command.

    mount /dev/sda8 /sysroot

  4. If the error message matched in step 4, check whether filesystem modules are loaded by issuing the command.

    lsmod |grep ext4

  5. If there is no output, then it confirms that the above issue is caused by missing filesystem module.

Missing filesystem modules in the kernel cmdline

BusyBox mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for dualboot installations.

  1. To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").

    modprobe ext4

  2. To verify if the issue is resolved, reissue the command.

    mount /dev/sda8 /sysroot

  3. If mount succeeded, issue the following command to boot into Alpine Linux.

    exit

Choose the appropriate solution based on your use case for a permanent fix:

  • If you are using grub, then ensure that GRUB_CMDLINE_LINUX line in the file /etc/default/grub has the appropriate filesystem module ext4 and rootfstype=ext4 as follows:

    Contents of /etc/default/grub

    ... GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4" ...
  • If you are using Syslinux, then ensure that APPEND root line in the file /boot/extlinux.conf has the appropriate filesystem module ext4 as follows:

    Contents of /boot/extlinux.conf

    ... APPEND root=/dev/sdXY modules=sd-load,usb-storage,ext4 quiet ...
Note: For both above cases, you may need to issue update-grub or update-extlinux after making above changes.
  • For a solution independent of bootloaders, ensure that the file /etc/mkinitfs/mkinitfs.conf has the necessary filesystem module in it. Refer Initramfs page for more information and recreate initramfs image.

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Setting_up_disks_manually&oldid=28815"