Setting up disks manually: Difference between revisions

From Alpine Linux
No edit summary
(The Issue template does not support subprojects other than aports. hence replaced it by external wiki link to bug report)
 
(49 intermediate revisions by 10 users not shown)
Line 1: Line 1:
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]].


The menu choices that are provided by <code>setup-alpine</code> can not cover all needs, however, it's possible to:
==='''Diskless Mode'''===
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.


* Call [[Alpine_setup_scripts#setup-disk|setup-disk]] directly, instead of through <code>setup-alpine</code>, and pass some specific partitioning parameters to it.
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 [[Create a Bootable Device|customizable boot device]], a 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.
* 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.


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


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.)
Alternately, use the <code>[[Alpine_setup_scripts#setup-lbu|setup-lbu]]</code> script to configure a "local backup" location for the [[#Diskless Mode|diskless]] system, and <code>[[Alpine_local_backup|lbu commit]]</code> to then save the local configuration state.
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> script and [[Create_a_Bootable_Device|create a  customizable boot device]].
Refer [[Alpine_local_backup#Saving_and_loading_ISO_image_customizations|Saving and loading ISO image customizations]] related to loading an .apkovl volume from system partitions.
As per Bug: [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10473 #10473] Storing local configs and the package cache on '''internal disks requires''' [[Alpine_local_backup#Saving_and_loading_ISO_image_customizations|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.
As per 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.
{{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.}}
* 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.
# mkfs.ext4 -O ^has_journal /dev/sdXY  # the "-O ^has_journal" DISABLES journaling ("^" means "not")
==='''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 Issue {{Issue|10474}}  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:
# 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]].
<code>cfdisk</code> will be used in all examples here as it is based on text menu without any dependencies:
The following step installs <code>cfdisk</code>:
{{cmd|# apk add cfdisk }}
=== Creating partitions ===
<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


(Beta refenence: [https://beta.docs.alpinelinux.org/user-handbook/0.1a/Installing/manual.html#_finalizing beta.docs.alpinelinux.org] )
=== 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.


= Using setup-alpine (setup-disk) features =
[[File:Cfdisk screenshot alpine 2024-03-04 143916.png|thumb|cfdisk screenshot ]]


== For "diskless" and "data" disk mode installs ==
To resize disk, launch the <code>cfdisk</code>:
{{cmd|# cfdisk {{path|/dev/sda}}}}


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


How to prepare writable storage space is explained in the section [[Setting_up_disks_manually#Manual_partitioning| manual partitioning]], below.
If a filesystem is resized with -f (online mode), then the system must be rebooted immediately after the change is made.


== For "sys" disk mode installs ==
{{cmd|# resize2fs -f {{path|/dev/sda3}}
&num; reboot}}


{{Draft|Some information on this page may be incomplete or outdate.}}
=== Formatting partitions ===


=== Disk layouts ===
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.
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 75: Line 208:


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 ===
Line 118: Line 250:


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


=== LVM ===
=== LVM ===
Line 145: Line 275:




 
== see also ==
 
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
= Manual partitioning =
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
 
 
== For "diskless" and "data" disk mode installs ==
 
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-Install|setting up a graphical environment]]).
 
The following example installs <code>cfdisk</code>, looks for existing partitions, and runs cfdisk against <code>/dev/sdX</code>:
# apk add cfdisk
# blkid
/dev/sdX1: LABEL="some" UUID="..." TYPE="vfat"
/dev/sdX2: LABEL="other" UUID="..." TYPE="ext4"
# cfdisk /dev/sdX
 
 
* Be aware of this Bug: [https://gitlab.alpinelinux.org/alpine/aports/-/issues/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.
 
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.
# apk add e2fsprogs
# mkfs.ext4 -O ^has_journal /dev/sdXY  # the "-O ^has_journal" DISABLES journaling ("^" means "not")
 
{{Note|IMPORTANT! There may be additional steps necessary to make proper use of the partition, see
[[Alpine_local_backup#Saving_and_loading_ISO_image_customizations|Saving_and_loading_ISO_image_customizations]].
}}
 
== For "sys" disk mode installs ==
 
<code>setup-disk</code> will by default set up a root partition, a separate /boot partition and a swap partition. If you want a different layout, you can manually create the partitions, filesystems and mount them on {{Path|/mnt}} (or any other mount point) then run:
 
{{Cmd|setup-disk /mnt}}
 
<code>setup-disk</code> will install your running system on the mounted root, detect your file system layout and generate an fstab.
 
If you're using the MBR, you are responsible for making the proper partition bootable and make sure the MBR is OK for extlinux. If you're going to use EFI, make sure you 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>.
 
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]]
* [[Replacing non-Alpine Linux with Alpine remotely]]
 
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]
 
<!--
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/
-->
 
 
<!--
== 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 ==
We need to install the software to create the filesystem ("format" the partition).
apk_add e2fsprogs
 
If you use an Alpine release older than 1.3.8 you will need to manually create a link to /etc/mtab.
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.
mke2fs -j /dev/md1
 
 
Now edit /etc/fstab and add your new partitions. Mine looks like this:
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 ==
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.
 
mv /var /var.tmp
mkdir /var
mount /var
mv /var.tmp/* /var
rmdir /var.tmp
 
Verify that everyting looks ok with the ''df'' utility.
~ $ df
Filesystem          1k-blocks      Used Available Use% Mounted on
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 ==
Now we have everything up and running. We need to make sure that everything will be restored during next reboot.
 
Create an initscript that will mount /var for you during boot. I call it /etc/init.d/mountdisk and it looks like this:
#!/sbin/runscript
start() {
        ebegin "Mounting /var"
        mount /var
        eend $?
}
stop() {
        ebegin "Unmounting /var"
        umount /var
        eend $?
}
 
Make it exectutable:
chmod +x /etc/init.d/mountdisk
 
'''NOTE:''' Since Alpine-1.7.3 a script named ''localmount'' is included so you will not need to create your own ''mountdisk'' script.
 
/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:
rc_add -k -s 06 mountdisk
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?}}
 
 
[[Category:Installation]]
[[Category:Installation]]
[[Category:Storage]]
[[Category:Storage]]

Latest revision as of 12:46, 29 October 2024

Alpine Linux can be installed to run in Diskless, Data and system Disk modes using setup-disk script. For traditional or classic harddisk install, refer System Disk Mode Installation.

Diskless Mode

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 setup-alpine 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 lbu. It enables committing and reverting system states by using .apkovl files that are saved to customizable boot device, a 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 local package cache on the writable storage.

Diskless Mode Installation

Following the Installation steps to complete the base configuration completes the pre-setup of "diskless" Alpine Linux system.

If a writable partition is available, setup-alpine 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.)

Alternately, use the setup-lbu script to configure a "local backup" location for the diskless system, and lbu commit to then save the local configuration state.

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 setup-bootable script and create a customizable boot device.

Refer Saving and loading ISO image customizations related to loading an .apkovl volume from system partitions.

As per Bug: #10473 Storing local configs and the package cache on internal disks requires 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.

As per Bug: #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.

Note: mkfs.ext4 creates ext4 fs with 64bit feature enabled by default, but extlinux may not be able to boot with that, see Issue #14895. You may need to add "-O ^has_journal,^64bit" to mkfs.ext4 to circumvent this.
  • 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.
# mkfs.ext4 -O ^has_journal /dev/sdXY   # the "-O ^has_journal" DISABLES journaling ("^" means "not")

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 /var directory tree get mounted from a persistent storage device (two newly created partitions). The directory /var holds e.g. all log files, mailspools, databases, etc., as well as lbu 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 steps to complete the base configuration completes the pre-setup of "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 setup-bootable. Refer Creating a bootable device for creating a bootable medium to boot the Data Disk Mode Installation.

As per Issue #10474 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 setup-alpine exits, and before rebooting:

  1. Identify the created data partition, e.g. /dev/sdXY, and its filesystemtype, e.g. using lsblk
  2. Manually edit the lbu backups location in /etc/lbu/lbu.conf and configure LBU_MEDIA=sdXY (according to the previous findings).
  3. Save the configuration on that partition for the next boot with lbu commit.
  4. If (a new) partition fails to get mounted, execute: mkdir /media/sdXY ; echo "/dev/sdXY /media/sdXY fstype noauto,rw 0 0" >> /etc/fstab, and try lbu commit again.

System Disk Mode

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

System Disk Mode Installation

If entire hard disk(s) is available for Alpine Linux and default layout is sufficient, using setup-alpine script with optional environment variables is the quickest and easiest way to install Alpine Linux. Refer custom layout for all other use cases.

Environment variables

The optional environment variables can be called either by setup-alpine script at the beginning of Installation or by setup-disk script 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 grub as bootloader. The disk will set to use gpt partition table.

# USE_EFI=1 BOOTSIZE=512 setup-alpine

Default Layout

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

The setup-alpine script based installation supports only default layout.

When two hard disks are selected, then setup-disk sets them up in RAID 1 array and if more than 2 disks are selected, then RAID 5 is used.

Custom Layout

To perform a traditional hard-disk installation of Alpine Linux without any constraints, setup-disk must be called with a MOUNTPOINT. setup-disk will then perform a traditional harddisk or System Disk mode install with MOUNTPOINT as root.

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

# mount /dev/sdXY /mnt

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

# mkdir -p /mnt/boot

Find the correct partition name for esp partition and mount it on the above mount point :

# mount /dev/sdXY /mnt/boot

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

# swapon /dev/sdXY

Install Alpine Linux using the following command:

# setup-disk -m sys /mnt

setup-disk will install Alpine Linux system on the mounted root, uses the filesystem used during formatting step and generates /etc/fstab automatically and also installs an appropriate bootloader. In most cases, you can just reboot to boot into newly installed Alpine Linux. You can also choose to customize further.

Manual partitioning


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 fdisk command available. Busybox `fdisk` is rather limited for edit operations. Instead, alpine allows you to install more complete partitioning tool packages like sfdisk (scriptable fdisk), gptfdisk, parted (CLI), cfdisk (text menus), or even gparted (after setting up a graphical environment). These tools can be installed even during Installation immediately after setting up base configuration.

cfdisk will be used in all examples here as it is based on text menu without any dependencies:

The following step installs cfdisk:

# apk add cfdisk

Creating partitions

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

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

Resizing an existing partition

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

Install the necessary filesystem tools to format the newly created partitions. Refer the filesystem page for the choices available in Alpine Linux.

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 29 Oct 2024.)

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.


see also