View source for Setting up disks manually

Alpine Linux can be installed to run in [[Diskless Mode|Diskless]], [[#Data Disk Mode|Data]] and [[#System Disk Mode|system  Disk]] modes using <code>[[Alpine_setup_scripts#setup-disk|setup-disk]]</code> script. For traditional or classic '''harddisk''' install, refer [[#System_Disk_Mode_Installation|System Disk Mode Installation]].

==='''Data Disk Mode'''===
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. 

==== Data Disk Mode Installation  ====

Following the [[Installation#Installation_Step_Details|Installation steps]] to complete the [[Installation#Base_configuration|base configuration]] completes the pre-setup of [[Diskless_Mode|"diskless"]] Alpine Linux system. 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>. Refer [[Create_a_Bootable_Device|Creating a bootable device]] for creating a bootable medium to boot the Data Disk Mode Installation.

As per Bug: [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10474 #10474], <Code>setup-alpine</Code> script 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:

# 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).
# Save the configuration on that partition for the next boot with <code>lbu commit</code>.
# 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.

==='''System Disk Mode'''===

System Disk Mode is the traditional harddisk installation. This is the mode suitable for most use cases including generic [[:Category:Desktop|desktop]], development machines etc..

==== System Disk Mode Installation ====

If entire hard disk(s) is available for Alpine Linux and [[#Default_Layout|default layout]] is sufficient, using <code>setup-alpine</code> script with optional [[#Environment variables|environment variables]] is the quickest and easiest way to [[Installation#setup-alpine_based_System_Disk_Install|install Alpine Linux]]. Refer [[Setting_up_disks_manually#Custom_Layout|custom layout]] for all other use cases.

===== Environment variables  ===== 

The '''optional''' environment variables can be called either by <code>setup-alpine</code> script at the beginning of [[Installation#Boot_Process|Installation]] or by <code>setup-disk</code> script [[Installation#Alternate_courses_of_action|later]]. 

* BOOTFS - The filesystem to use on /boot, defaults to ext4, also allows ext2, ext3, (flat) btrfs, xfs and vfat (required on UEFI).
* BOOTLOADER - Bootloader to use. Defaults to syslinux, but also allows using grub, unless UEFI is used, in which case grub is required.
* BOOTSIZE - The size of /boot.
* DISKLABEL - The type of partition table to use. Defaults to dos, but also allows using gpt, unless UEFI is used, in which case gpt is required.
* ROOTFS - The filesystem to use on /, defaults to ext4, also allows ext2, ext3, (flat) btrfs and xfs.
* USE_EFI - Enable this to force using UEFI.

Environment variables can be combined. For e.g, the following command creates 512MB '''/boot''' partition on the selected hard disk, with '''vfat''' filesystem and uses <code>grub</code> as bootloader. The disk will set to use gpt partition table.
 
{{cmd| <nowiki>
# USE_EFI=1 BOOTSIZE=512 setup-alpine
</nowiki>}}

===== Default Layout  ===== 

All existing partitions on the chosen hard disk(s) are deleted by <code>setup-disk</code> and it creates 3 partitions i.e  '''(/)'''root partition, a '''/boot''' partition and a '''swap''' partition.  The manual pages of <code>setup-disk</code> refers this as DISKDEV mode.  

The <code>setup-alpine</code> script based [[Installation#System_Disk_mode_Install|installation]] supports only default layout.

When two hard disks are selected, then <code>setup-disk</code> sets them up in [[#RAID|RAID 1]] array and if more than 2 disks are selected, then [[#RAID|RAID 5]] is used. 

===== Custom Layout =====

To perform a traditional hard-disk installation of Alpine Linux without any constraints, <code>setup-disk</code> must be called with a MOUNTPOINT. <code>setup-disk</code> will then perform a traditional harddisk or [[#System_Disk_mode|System Disk mode]] install with MOUNTPOINT as root.

To install Alpine Linux using custom layout follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[#Base_configuration|base configuration]]. If necessary partition(s) are unavailable, manually [[#Creating_partitions|create]], [[#Formatting_partitions|format]] and mount them on a mount point i.e say {{Path|/mnt}} or any other as follows:

{{Cmd|# mount /dev/sdXY /mnt}}

If you're using EFI, make sure you create a mount point <code>/mnt/boot</code>.  

{{Cmd|# mkdir -p /mnt/boot}}

Find the correct partition name for <code>esp</code> partition and mount it on the above mount point :

{{Cmd|# mount /dev/sdXY /mnt/boot}}

If 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 install Alpine Linux system on the mounted root, uses the [[Filesystems|filesystem]] used during [[#Formatting_partitions|formatting]] step and generates {{Path|/etc/fstab}} automatically and also installs an appropriate [[Bootloaders|bootloader]]. In most cases, you can just [[Installation#Reboot|reboot]] to boot into newly installed Alpine Linux. You can also choose to [[Installation#Post-Installation|customize]] further.

== Manual partitioning ==
<br>
{{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.}}

=== Partitioning tools ===

The installation image enviroment may have only the very basic busybox built-in <code>fdisk</code> command available. Busybox `fdisk` is rather limited for edit operations.  Instead, 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]]).
These tools can be installed even during [[Installation]] immediately after setting up [[Installation#Base_configuration|base configuration]].

=== Creating partitions ===

<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. Alternately, {{Pkg|<code>sfdisk</code>}} is available and can be installed without network.

The following step installs the package {{Pkg|<code>cfdisk</code>}}: 
{{cmd|# apk add cfdisk }}

<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>:

{{cmd|# blkid}}
<pre>
/dev/sdX1: LABEL="some" UUID="..." TYPE="vfat"
/dev/sdX2: LABEL="other" UUID="..." TYPE="ext4"
</pre>

When <code>cfdisk</code> is run as follows, it looks for existing partitions on the disk {{Path|/dev/sdX}} :
{{cmd|# cfdisk /dev/sdX}}

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

=== Resizing an existing partition ===

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

[[File:Cfdisk screenshot alpine 2024-03-04 143916.png|thumb|cfdisk screenshot ]]

To resize disk, launch the <code>cfdisk</code>: 
{{cmd|# cfdisk {{path|/dev/sda}}}}

# 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''

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

{{cmd|# resize2fs -f {{path|/dev/sda3}}
&num; reboot}}

=== Formatting partitions ===

Install the necessary [[Filesystems#Filesystem_Tools|filesystem tools]] to [[Filesystems#Formatting_Partitions|format]] the newly [[#Creating_partitions|created]] partitions. 
Refer the [[Filesystems|filesystem]] page for the choices available in Alpine Linux. 

== Disk layouts ==

{{Draft|This entire section including RAID, Encryption and LVM needs to be updated.}}

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.

Your {{Path|/boot}} directory cannot reside on an encrypted or LVM volume, at least not with Alpine's default bootloader (extlinux). (Grub2 can deal with {{Path|/boot}} being on an LVM volume.) The usual practice is to create a small partition for {{Path|/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 {{Path|/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 {{Path|/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:

<pre>
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 |
  |                                                |  |                                                |
  +------------------------------------------------+  +------------------------------------------------+

</pre>

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

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

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 {{Path|/dev/md<i>i</i>}} device directly to [[setup-disk]]. When you're finished, be sure to disassemble the RAID array before rebooting.

If <code>setup-disk</code> sees that you're using RAID, either because you gave it the <code>-r</code> switch, or multiple devices, or a {{Path|/dev/md<i>i</i>}} 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 <code>setup-disk</code> 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 <code>$MNT</code> holds the root directory you're installing into:

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

{{Todo|Does adding the <code>--update</code> option to <code>extlinux ...</code> suffice to make {{Path|/boot/extlinux.conf}} be regenerated? Or do we need to manually tweak that file, or run <code>update-extlinux</code>, as well?}}

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 ===

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.

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

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

{{Todo|Does adding the <code>--update</code> option to <code>extlinux ...</code> suffice to make {{Path|/boot/extlinux.conf}} be regenerated? Or do we need to manually tweak that file, or run <code>update-extlinux</code>, as well?}}

You might also need to manually tweak {{Path|$MNT/etc/fstab}}.

=== LVM ===

<code>setup-disk</code> 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 <code>vgchange -ay</code>, format and mount your volumes, and supply the root mountpoint to [[setup-disk]]. When you're finished, be sure to
{{Cmd|umount ...
vgchange -an}}
before rebooting.


If <code>setup-disk</code> sees that you're using LVM, perhaps because you gave it the <code>-L</code> 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 <code>$MNT</code> holds the root directory you're installing into:

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

{{Todo|Does adding the <code>--update</code> option to <code>extlinux ...</code> suffice to make {{Path|/boot/extlinux.conf}} be regenerated? Or do we need to manually tweak that file, or run <code>update-extlinux</code>, as well?}}

You might also need to manually tweak {{Path|$MNT/etc/fstab}}.


== see also ==
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]
[[Category:Installation]]
[[Category:Storage]]