Alpine Linux - User contributions [en]

Immutable root with atomic upgrades

2021-12-31T14:23:42Z

Garritfra: /* Bootloader installation */ add reference to btrfs page

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks [[BTRFS|btrfs]] driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2021-12-31T14:22:47Z

Garritfra: /* File system structure */ add reference to btrfs page

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks [[BTRFS|btrfs]] driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2021-12-31T14:21:45Z

Garritfra: /* Preparation */ add reference to btrfs page

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks [[BTRFS|btrfs]] driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2021-12-31T14:21:25Z

Garritfra: /* What? */ add reference to btrfs page

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Production DataBases : mysql

2021-12-31T14:20:50Z

Garritfra: /* File system notes about the databases managed */ add reference to btrfs page

[https://mariadb.org/ MariaDB] is a community-developed fork of the MySQL relational database management system intended to remain free under the GNU GPL. It is notable for being led by the original developers of MySQL, who forked it due to concerns over its acquisition by Oracle.

This page assumed that you have a general knowledge about MariaDB, so if you are new to MySQL first take a look at the [[MariaDB|MariaDB wiki page]] for information about how are packaged for alpine linux.

== Installation ==

Alpine Linux has dummy counterparts packages for those that are not close to that change from ''mysql'' to ''mariadb'' naming packages, please check the [[MariaDB|MariaDB wiki page]] for more information.

Take in consideration that the user <code>mysql</code> was created during instalation of packages, in the initialization section two users will be created in database init: <code>root</code> and <code>mysql</code>, and in that point only if are in their respective system accounts, will be able to connect to the database service.

<pre><nowiki>
apk add mysql mysql-client
</nowiki></pre>

That will install the most used ones.. <code>mariadb-cient</code> and <code>mariadb-server</code>, rest of packages are brief described here for more information, here are listed in orden of relevance for production server

{| class="wikitable"
|-
! MySQL name package !! Since Alpine: !! Brief usage !! Related package
|-
| mysql || v2 || it's a dummy package to easy install of mariadb || mariadb
|-
| mysql-client || v2 || it's a dummy package to easy install of commands tools || mariadb-client
|-
| mariadb || v2 || server equivalent to mysql-server || mariadb-common
|-
| mariadb-client || v2 || connection command line and tools || mariadb-common
|-
| mariadb-doc || v3.0 || manpages are there! || man man-pages
|-
| mariadb-connector-odbc || edge || coding or making OS level connections, to any DB without libs install || .
|-
| mariadb-connector-c || v3.8 || coding connection on C sources || mariadb-connector-c-dev
|-
| mariadb-backup || v3.8 || to external backup devices, not widely used, in past was inside mariadb package || .
|-
| mariadb-server-utils || v3.8 || server commands not widely used, in past was inside mariadb package || .
|-
| mariadb-dev || v3.1 || Need for compilations depends on source code || .
|-
| mariadb-test || v3.3 || testing suite from MariaDB tools || .
|-
| mariadb-mytop || v3.9 || data performance monitoring || .
|-
| mariadb-plugin-rocksdb || v3.9 || plain key-value event relational for data || .
|-
| mariadb-static || v3.8 || static libs for static non depends linking in builds || .
|-
| mariadb-embedded || v3.9 || the libmysqld identical interface as the C client || mariadb-embedded-dev
|-
| mariadb-embedded-dev || v3.9 || use the normal mysql.h and link with libmysqld instead of libmysqlclient || mariadb-dev
|-
| mariadb-openrc || v3.8 || separate scripts, in past was embebed on server package || .
|}

== Initialization ==

The alpine package of MySQL/MariaDB are like normal tarball of MySQL one, admins must be know what they want.. there's no automatic window-like here.

The ''datadir'' are located to <code>/var/lib/mysql</code> must be owned by the mysql user and group. You can modify this behavior but must edit the service file at <code>/etc/init.d</code> directory. Also, you need to set <code><nowiki>datadir=<YOUR_DATADIR></nowiki></code> under section <code>[mysqld]</code> at the config file.

# Initialize the main mysql database, and the data dir as standardized to <code>/var/lib/mysql</code> by the rc script
# Then initialize the service, root account and socket connection are enabled without password at this point
# Setup the root account by asignes a proper password, this are purely paranoid. due next step already do that!
# Setup and init the installation by running the <code>mysql_secure_installation</code>
# Setup permissions for manage others users and databases

<pre>
<nowiki>
mysql_install_db --user=mysql --datadir=/var/lib/mysql

rc-service mariadb start

mysqladmin -u root password toor
</nowiki>
</pre>

After that, all are initializated to proceed with configuration, now can be done using the <code>
mysql_secure_installation</code> script at the next section:

== Configuration ==

In order to finish setup into '''MariaDB''' now provide '''this script called <code>mysql_secure_instalation</code> that also are present as <code>mariadb-secure-installation</code>''', too. This script provides minimal and security setup to the database, and here are the questions made explained:

# '''Enter current password for root (enter for none):''' this are if you previously setup as we done in previous section a root password, just provide it and press enter, '''must be provided due we already set previously''' and from now, this sript will access to the engine and alter many setting on the database. Correct respond are <code>OK, successfully used password, moving on...</code>
# '''Switch to unix_socket authentication [Y/n]''' Setting the root password or using the unix_socket ensures that only admins can log into engine database. Since mysql 5.6 and mariadb 10.2 a new auth mechanish are set, by socket authentiaction, when system user are same as mysql/mariadb user, in this case, no password are need. In production servers this are not the case and must be disabled, '''so answer NO''', and response will be <code>... skipping.</code>
# '''Change the root password? [Y/n]''' this answer are here only if the first one are just enter, or if can provide a better passowrd if no unix socket are set. Just press "n" only if you provided a good password, otherwise just
# '''Remove anonymous users? [Y/n]''' this permits remove the anonymous user created to log using socket authentication, only working on unix-like system. In any case, '''production system must remove it, so answer Y''' and proper respond must be <code>... Success!</code>.
# '''Disallow root login remotely? [Y/n]''' Normally, root should only be allowed to connect from 'localhost'. This ensures that someone cannot guess at the root password from the network. For sure answer Y''' and proper respond must be <code>... Success!</code>.
# '''Remove test database and access to it? [Y/n]''' By default, MariaDB comes with a database named 'test' that anyone can access. This is also intended only for testing, and should be removed, so answer Y''' and proper respond must be <code>... Success!</code>.
# '''Reload privilege tables now? [Y/n]''' Reloading the privilege tables will ensure that all changes made so far will take effect immediately, so answer Y''' and proper respond must be <code>... Success!</code>.

After reponse all the questions.. restart the service with <code>rc-service mariadb restart</code>

=== Configuration files ===

Due today were influenced by systemd standardization, the famous <nowiki>my.cnf</nowiki> are not more the main config file for the server engine. Now only few variables are defined there and all the settings are provided by independent files into the <code>/etc/my.cnf.d/</code> directory, user own config files are under <code>~/.my.cnf</code> config file of each home dir, and are read after global ones; so then we have:

{| class="wikitable"
|-
! Config file !! Path and name !! Versions of Alpine !! Contents to configure
|-
| my.cnf || <nowiki>/etc/mysql/my.cnf</nowiki> || v2 to v3.8 || All the directives, Global config file
|-
| mariadb-server.cnf || /etc/my.cnf.d/mariadb-server.cnf || since 3.9 || First Global config file, main directives
|-
| .my.cnf || <nowiki>$HOME</nowiki> || all || user name only config directives
|}

=== Production settings ===

These setting are only recommended for some server settings, there are the recommendation for high production settings:

{| class="wikitable"
|-
! Config setting !! Default !! Recommended !! Explanation
|-
| main ram || 2G || 8G - 16G || MariaDB/MySQL can run with 512M or 1G of ram, high production must use minimun of 4G or more.
|-
| data dir disk type || any || SSD || MariaDB/MySQL must run with faster SSD if high request will be produced.
|-
| collation_server || utf8_unicode_ci || utf8mb4_unicode_ci || With 8mb4 some characters are able to use more than a single byte.
|-
| character_set_client || iso8859-1 || utf8 or utf8mb4 || Important due are standard, for left to right use 8mb4 flavor
|-
| max_connections || 151 || 100 || total_connections = total_processes * (total_threads + script_servers + 1)
|-
| max_heap_table_size || 16M || 32M || allocate more memory to memory tables, for memory storage engines
|-
| tmp_table_size || 16M || 32M || It allows the sub queries to remain more in memory, making them faster
|-
| join_buffer_size || 32M || 64M || It allows the join queries to remain more in memory rather in temp files
|-
| innodb_file_format || unset || Barracuda || will allow longer indexes for important most used tables
|-
| innodb_large_prefix || unset || 1 || Must set if Barracuda file format are choosen
|-
| innodb_buffer_pool_size || 128M || 456M || hold as much tables and indexes in system memory as is possible
|-
| innodb_read_io_threads || 16 || 32 || On high I/O systems, a value greater than 1 may allow the disk I/O to be more sequential
|-
| innodb_write_io_threads || 16 || 32 || Only if you have SSD storage for the data MySQL/MariaDB database and temp files
|-
| innodb_buffer_pool_instances || 1 || 2 or 4 || Only for older MySQL/MariaDB engines,
|-
| innodb_io_capacity || 200 || 1200 - 2600 || Only if you have SSD storage for the data MySQL/MariaDB database and temp files
|-
| innodb_io_capacity_max || 200 || 2400 - 5200 || Only if you have SSD storage for the data MySQL/MariaDB database and temp files
|}

If you have SSD disks, use the recommended suggestion, otherwise, use minimum suggested. If you have physical hard drives, use 2000 * the number of active drives in the array. If using NVMe or PCIe Flash, much larger numbers as high as 200000 can be used, but those lasted storage devices will be a short life of course.

Newer system Alpine packages can set in independent files in any case those commands always works and where are not apply just will ignore the output:

* On older Alpine system must set config files for MAX ALLOWED PACKETS to minimun proper amount:

<pre>
<nowiki>
sed -i "s|.*max_allowed_packet\s*=.*|max_allowed_packet = 100M|g" /etc/mysql/my.cnf
sed -i "s|.*max_allowed_packet\s*=.*|max_allowed_packet = 100M|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>
</pre>

* Only allow local connections on cases where there's only one server or no expected to connect from others:

<pre>
<nowiki>
sed -i "s|.*bind-address\s*=.*|bind-address=127.0.0.1|g" /etc/mysql/my.cnf
sed -i "s|.*bind-address\s*=.*|bind-address=127.0.0.1|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>
</pre>

* If are not in domain controller, dont search for hostnames to improve performance responses (ideal for local only servers):

<pre>
<nowiki>
sed -i "s|.*skip-networking.*|skip-networking|g" /etc/mysql/my.cnf
sed -i "s|.*skip-networking.*|skip-networking|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>
</pre>

* Set default charset to UTF8MB4, in newer versions (since Alpine v3.9), just added a new file to added thus customization, but older versions (below Alpine v3.8)of the package does not have a charset section, so you must added manually to the main configuration in each respective section:

<pre>
<nowiki>
cat > /etc/my.cnf.d/mariadb-server-default-charset.cnf << EOF
[client]
default-character-set = utf8mb4

[mysqld]
collation_server = utf8mb4_unicode_ci
character_set_server = utf8mb4

[mysql]
default-character-set = utf8mb4
EOF
</nowiki>
</pre>

== Updating or comming from upgrading ==

Mayor Upgrades beetween Alpine linux version are so easy as change the repository version, but the MySQL/MariaDB engine need some extra steps when this are performed:

Upgrade databases on major releases
Upon a major version release of mariadb (for example mariadb-10.1.10-1 to mariadb-10.1.18-1), it is wise to upgrade databases:

# keep the old database (mysql sheme) structure of the engine daemon, currently this are not more the case, today this not make sense anymore
# upgrade the MariaDB/MySQL packages, of course with must be done if the upgrade process to mayor alpine version does not!
# run the <code>mysql_upgrade -u root -p</code> script, providing the password or root, (from the new package version) against the old still-running database (mysql sheme). This will produce some error messages; however, the upgrade will succeed.
# Restart the service

If are unable to run ''mysql_upgrade'' because MySQL cannot start try run MySQL in safemode with <code>mysqld_safe --datadir=/var/lib/mysql/</code> command and then run the <code>mysql_upgrade -u root -p</code> script.

= Relevant important notes =

== File system notes about the databases managed ==

'''BTRFS Notes'''

If the database (in <code>/var/lib/mysql</code>) resides on a [[BTRFS|btrfs]] file system, you should consider disabling '''Copy-on-Write''' for the directory before creating any database (schemes), after initialization you can enabled again. But .. on every database creation (scheme creation), you must disabled again, to avoid corrupted data.

'''ZFS Bock sizes'''

ZFS, unlike most other file systems, has a variable record size, or what is commonly referred to as a block size. By default, the recordsize on ZFS is 128KiB, which means it will dynamically allocate blocks of any size from 512B to 128KiB depending on the size of file being written. Most RDBMSes work in 8KiB-sized blocks by default. Although the block size is tunable for MySQL/MariaDB use an 8KiB block size by default.

It is usually desirable to tune ZFS instead to accommodate the databases, using a command such as <code>zfs set recordsize=8K /var/lib/mysql</code> (or change /var/lib/mysql to the mount point where /var/lib/mysql resides) and in the interest of saving memory, it is best to simply disable ZFS's caching of the database's file data and let the database do its own job with <code>zfs set primarycache=metadata /var/lib/mysql</code> (or change /var/lib/mysql to the mount point where /var/lib/mysql resides).

But beware, these kinds of tuning parameters are only if RDBMSes are setup in dedicated partitions, if your root and of course database are all in one partition, dont do that. Separate ones.

== Restore root password ==

<pre>
<nowiki>
rc-service mysql stop

kill `cat /run/mysqld/mysqld.pid`

/usr/bin/mysqld --datadir=/var/lib/mysql --pid-file=/run/mysqld/mysqld.pid --skip-grant-tables --skip-networking &

mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'MyNewPass';FLUSH PRIVILEGES;ALTER USER 'root'@'localhost' IDENTIFIED BY 'MyNewPass';FLUSH PRIVILEGES;set password = password('MyNewPass');"

kill `cat /run/mysqld/mysqld.pid`

rc-service mariadb restart
</nowiki>
</pre>

= See Also =

* [[MariaDB|MariaDB wiki page]]
* [[Production LAMP system: Lighttpd + PHP + MySQL]]
* [[Alpine newbie developer]]

[[Category:Newbie]]
[[Category:Server]]
[[Category:Database]]
[[Category:Development]]
[[Category:Security]]
[[Category:Production]]

Bootloaders

2021-12-31T14:20:17Z

Garritfra: /* Installing Syslinux */ add reference to btrfs page

This page shows the basic steps you need to perform, if you for any reason want to switch bootloaders or apply some manual configuration.

<code>rEFInd</code> is an easy to use EFI boot menu that allows booting different operating systems. 
<code>Syslinux</code> is the default light-weight bootloader used in Alpine. 
<code>Grub</code> is a standard linux boot loader. 
<code>EFI Boot Stub</code> allows booting linux directly from a motherboard supporting UEFI or another bootloader. 

= rEFIind =

For (U)EFI systems, the <code>refind</code> package can provide a graphical EFI boot menu that allows to boot operating systems that are found on the available partitions.

If <code>refind</code> is not yet available in the used alpine release, it may be installed in another dual/multi-booted linux distribution.

For example, with a Debian based distribution, it can be installed to the EFI partition like this:

apt install refind # installs the debian package
refind-install --alldrivers # installs refind to the EFI partitioon

(The --alldrivers option includes all filesystem drivers instead of only the one needed to load the currently running kernel, to allow finding and booting operating systems from more partitions.)

And a first (default) boot menu line needs to be configured with Alpine's default boot parameters. Assuming the bootable partition is mounted at <code>/media/sdXY</code> it can be done like this (at time of writing):
echo '"Alpine" "modules=loop,squashfs,sd-mod,usb-storage quiet initrd=\boot\intel-ucode.img initrd=\boot\amd-ucode.img initrd=\boot\initramfs-lts"' > /media/sdXY/boot/refind_linux.conf

{{Note|

# At the time of writing, it was still needed to use backslashes in the .conf file.
# The path in the config file needs to be relative to the partition that the kernel resides on. If <code>/boot</code> resides on its own separate partition, then <code>\boot</code> needs to be removed from the paths. }}

= Installing Syslinux =

If you want to switch from another bootloader back to Syslinux, or if you for some reason want to install Syslinux manually, the following steps are required.

Install the <code>syslinux</code> package:

<pre>apk add syslinux</pre>

If you're using GPT partitions, install the GPT MBR onto the drive you want to install the bootloader on (in this case <code>/dev/sda</code>):

<pre>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</pre>

Or if you're using DOS partitions, install the DOS MBR instead:

<pre>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</pre>



Next install the required Syslinux binaries. Despite being called <code>extlinux</code>, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, [[BTRFS|btrfs]], XFS, and UFS/FFS filesystems.

<pre>extlinux --install /boot</pre>

The configuration file is located in <code>/boot/extlinux.conf</code>.
Alpine ships with a script called <code>update-extlinux</code> which automatically (re)generates this file, for example on updates to Syslinux.
The settings for this script can be found in <code>/etc/update-extlinux.conf</code>, including the option to disable automatic overwriting of <code>/boot/extlinux.conf</code>.
You can also place additional menu entries in the <code>/etc/update-extlinux.d/</code> directory, e.g. for dual booting.

=== EFI ===

{{Todo|Work in progress. This should at least get you started.}}

Assuming <code>/mnt</code> is a FAT32 partition of type EF00 and <code>/boot</code> belongs to the rootfs created after running <code>setup-disk</code>:

<pre>
mkdir -p /mnt/EFI/syslinux
cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/
cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg
cp /boot/vmlinuz* /mnt/
cp /boot/initramfs* /mnt/
</pre>

You may need to modify <code>/mnt/EFI/syslinux/syslinux.cfg</code> to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries),
or copy the files to <code>/mnt/EFI/syslinux</code> instead (XXX: untested).

= GRUB =

To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:

<pre>apk del syslinux
apk add grub grub-bios</pre>

For EFI, install Grub's EFI package instead. Note that <code>/boot</code> has to be an EFI compatible filesystem like FAT32.

<pre>apk add grub-efi</pre>

Next install the MBR and GRUB binaries to disk for BIOS mode:

<pre>grub-install /dev/vda</pre>

For EFI mode:

<pre>grub-install --target=x86_64-efi --efi-directory=/boot</pre>

GRUB ships with an automatic config generator, including some automatic detection of other operating systems installed on the device:

<pre>grub-mkconfig -o /boot/grub/grub.cfg</pre>

This script can be configured via the <code>/etc/default/grub</code> file.
See [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html] for a list of available options.

= EFI Boot Stub =

To boot directly from your motherboard's UEFI boot menu, a boot entry needs
to be created with either a UEFI shell or ''efibootmgr''.

== efibootmgr ==

Install efibootmgr:
<pre>apk add efibootmgr</pre>

Create a boot entry. It's recommended to do this in a script, as efibootmgr
does not allow editing entries.

<pre>#!/bin/sh

params="root=/dev/sdXZ rw \
initrd=\intel-ucode.img \
initrd=\initramfs-lts"

efibootmgr --create --label "Alpine Linux" \
--disk /dev/sdX --part Y \
--loader /vmlinuz-lts \
--unicode "${params}" \
--verbose
</pre>

Where <code>/dev/sdXY</code> contains the EFI partition and <code>/dev/sdXZ</code> contains the root partition. If you are using {{Pkg|linux-edge}}, replace <code>lts</code> with <code>edge</code> in the script

{{Note|
The kernel contains the [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/init/do_mounts.c#n254 exhaustive list] of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.
}}

Optionally, set the newly created entry as the default:

<pre>efibootmgr -n XXXX</pre>

Where <code>XXXX</code> is the boot number of the new entry.

{{Note|
The loader and initrd file arguments are relative to the EFI partition. In a default installation, alpine places these files in <code>/boot/</code>, while EFI is mounted to <code>/boot/efi/</code>. You can either update fstab to mount EFI at <code>/boot/</code>, or manually copy them to <code>/boot/efi/</code>. }}

= External Links =
* [https://www.denx.de/wiki/U-Boot/ReleaseCycle U-Boot Release Cycle]

[[Category:Installation]]
[[Category:Booting]]

Alpine configuration management scripts

2021-12-31T14:19:35Z

Garritfra: /* setup-disk */ add reference to btrfs page

Feature descriptions for available Alpine Linux setup scripts ({{Path|/sbin/setup-*}}).

These scripts can be installed from alpine-conf package using apk.

(Some particular example usages can be seen at [[Alpine_newbie_install_manual#Ways_to_install_Alpine_into_machines_or_virtuals|Alpine for new users install manuals]].)

== setup-alpine ==

This is the main Alpine configuration and installation script.

The script interactively walks the user through executing several auxiliary <code>setup-*</code> scripts, in the order shown below.

The bracketed options represent example configuration choices, formatted as they may be supplied when manually calling the auxiliary setup scripts, or using a <code>setup-alpine</code> "answerfile" (see below).

# <code>setup-keymap</code> [us us]
# [[#setup-hostname|setup-hostname]] [-n alpine-test]
# [[#setup-interfaces|setup-interfaces]] [-i < interfaces-file]
# <code>/etc/init.d/networking --quiet start &</code>
# if none of the networking interfaces were configured using dhcp, then: <code>[[#setup-dns|setup-dns]]</code> [-d example.com -n "192.168.0.1 [...]"]
# set the root password
# if not in quick mode, then: <code>[[#setup-timezone|setup-timezone]]</code> [-z UTC | -z America/New_York | -p EST+5]
# enable the new hostname (<code>/etc/init.d/hostname --quiet restart</code>)
# add <code>networking</code> and <code>urandom</code> to the '''boot''' rc level, and <code>acpid</code> and <code>crond</code> to the '''default''' rc level, and start the '''boot''' and '''default''' rc services
# extract the fully-qualified domain name and hostname from {{Path|/etc/resolv.conf}} and <code>hostname</code>, and update {{Path|/etc/hosts}}
# <code>[[#setup-proxy|setup-proxy]]</code> [-q <nowiki>"http://webproxy:8080"</nowiki>], and activate proxy if it was configured
# <code>setup-apkrepos</code> [-r (to select a mirror randomly)]
# if not in quick mode, then: <code>[[#setup-sshd|setup-sshd]]</code> [-c openssh | dropbear | none]
# if not in quick mode, then: <code>setup-ntp</code> [-c chrony | openntpd | busybox | none]
# if not in quick mode, then: <code>DEFAULT_DISK=none</code> <code>[[#setup-disk|setup-disk]]</code> <code>-q</code> [-m data /dev/sda] (see [[Installation#Installation_Overview]] about the disk modes)
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-lbu</code> [/media/sdb1]
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-apkcache</code> [/media/sdb1/cache | none]

<code>setup-alpine</code> itself accepts the following command-line switches

{{Define|-h|Shows the up-to-date usage help message.}}

{{Define|-a|Create an overlay file: this creates a temporary directory and saves its location in ROOT; however, the script doesn't export this variable so I think this feature isn't currently functional.}}
;-c <var>answerfile</var>
:Create a new "answerfile", with default choices. You can edit the file and then invoke <code>setup-alpine -f <var>answerfile</var></code>.
;-f <var>answerfile</var>
:Use an existing "answerfile", which may override some or all of the interactive prompts.
{{Define|-q|Run in "quick mode".}}

 

== setup-hostname ==

:<code>setup-hostname</code> [-h] [-n hostname]

Options:

'''-h''' <var>Show help</var>

'''-n''' <var>Specify hostname</var>

This script allows quick and easy setup of the system hostname by writing it to {{Path|/etc/hostname}}. The script prevents you from writing an invalid hostname (such as one that used invalid characters or starts with a '-' or is too long).
The script can be invoked manually or is called as part of the <code>setup-alpine</code> script.

 

== setup-interfaces ==
{{Cmd|setup-interfaces [-i < <var>interfaces-file</var>]}}

Note that the contents of <var>interfaces-file</var> has to be supplied as stdin, rather than naming the file as an additional argument. The contents should have the format of {{Path|/etc/network/interfaces}}, such as:

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp
hostname alpine-test

 

== setup-dns ==

:<code>setup-dns</code> [-h] [-d domain name] [-n name server]

Options:

'''-h''' <var>Show help</var>

'''-d''' <var>specify search domain name</var>

'''-n''' <var>name server IP</var>

The setup-dns script is stored in {{Path|/sbin/setup-dns}} and allows quick and simple setup of DNS servers (and a DNS search domain if required). Simply running <code>setup-dns</code> will allow interactive use of the script, or the options can be specified.

The information fed to this script is written to {{Path|/etc/resolv.conf}}

Example usage (with 192.168.0.1 being the local router/dns-forwarder): {{Cmd|setup-dns -d example.org -n 192.168.0.1}}

Example {{Path|/etc/resolv.conf}}:

search example.org
nameserver 192.168.0.1

It can be run manually but is also invoked in the <code>setup-alpine</code> script unless interfaces are configured for DHCP.

 

== setup-timezone ==
:<code>setup-timezone</code> [-z UTC | -z America/New_York | -p EST+5]

Can pre-select the timezone using either of these switches:

'''-z''' <var>subfolder of</var> {{Path|/usr/share/zoneinfo}}

'''-p''' <var>POSIX TZ format</var>

 

== setup-proxy ==
:<code>setup-proxy</code> [-hq] [PROXYURL]

Options:

'''-h''' <var>Show help</var>

'''-q''' <var>Quiet mode</var> prevents changes from taking effect until after reboot

This script requests the system proxy to use in the form <code>http://<proxyurl>:<port></code> for example:
<code><nowiki>http://10.0.0.1:8080</nowiki></code>

To set no system proxy use <code>none</code>.
This script exports the following environmental variables:

<code>http_proxy=$proxyurl</code>

<code>https_proxy=$proxyurl</code>

<code>ftp_proxy=$proxyurl</code>

where <code>$proxyurl</code> is the value input.
If <code>none</code> was chosen then the value it is set to a blank value (and so no proxy is used).

 

== setup-apkrepos ==
:<code>setup-apkrepos</code> [-fhr] [REPO...]

Setup <code>apk</code> repositories.

options:

'''-f''' <var>Detect and add fastest mirror</var>

'''-r''' <var>Add a random mirror and do not prompt</var>

'''-1''' <var>Add first mirror on the list (normally a CDN)</var>

This is run as part of the <code>setup-alpine</code> script.

 

== setup-sshd ==

:<code>setup-sshd</code> [-h] [-c choice of SSH daemon]

Options:

'''-h''' <var>Show help</var>

'''-c''' <var>SSH daemon</var> where SSH daemon can be one of the following:

<code>openssh</code> install the {{Pkg|openSSH}} daemon

<code>dropbear</code> install the {{Pkg|dropbear}} daemon

<code>none</code> Do not install an SSH daemon

Example usage: {{Cmd|setup-sshd -c dropbear}}

The setup-sshd script is stored in {{Path|/sbin/setup-sshd}} and allows quick and simple setup of either the OpenSSH or Dropbear SSH daemon & client.
It can be run manually but is also invoked in the <code>setup-alpine</code> script.

 

== setup-ntp ==

''From [https://en.wikipedia.org/wiki/Network_Time_Protocol Wikipedia]'':

The '''Network Time Protocol (NTP)''' is a networking protocol for clock synchronization between computer systems over packet-switched, variable-latency data networks.

 

{{Cmd|usage: setup-ntp [-h] [-c choice of NTP daemon]

Setup NTP time synchronization

options:
-h Show this help
-c Choice of NTP daemon: busybox openntpd chrony none}}

<code>setup-ntp</code> script is stored in {{Path|/sbin/setup-ntp}} and allows quick and simple setup of the NTP client,
It can be run manually but is also invoked in the <code>setup-alpine</code> script.

 

== setup-disk ==

:<code>DEFAULT_DISK=none setup-disk -q</code> [-m data | sys] [<var>mountpoint directory</var> | /dev/sda ...]

In "sys" mode, it's an installer, it permanently installs Alpine on the disk, in "data" mode, it provides a larger and persistent /var volume.

This script accepts the following command-line switches:

;-k <var>kernel flavor</var>
;-o <var>apkovl file</var>
:Restore system from <var>apkovl file</var>
;-m data | sys
:Don't prompt for installation mode. With '''-m data''', the supplied devices are formatted to use as a {{Path|/var}} volume.
{{Define|-r|Use RAID1 with a single disk (degraded mode)}}
{{Define|-L|Create and use volumes in a LVM group}}
;-s <var>swap size in MB</var>
:Use 0 to disable swap
{{Define|-q|Exit quietly if no disks are found}}
{{Define|-v|Verbose mode}}

The script also honors the following environment variables:

<code>BOOT_SIZE</code>
:Size of the boot partition in MB; defaults to 100. Only used if '''-m sys''' is specified or interactively selected.

<code>SWAP_SIZE</code>
:Size of the swap volume in MB; set to 0 to disable swap. If not specified, will default to twice RAM, up to 4096, but won't be more than 1/3 the size of the smallest disk, and if less than 64 will just be 0. Only used if '''-m sys''' is specified or interactively selected.

<code>ROOTFS</code>
:Filesystem to use for the / volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 [[BTRFS|btrfs]] xfs.

<code>BOOTFS</code>
:Filesystem to use for the /boot volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 [[BTRFS|btrfs]] xfs.

<code>VARFS</code>
:Filesystem to use for the /var volume; defaults to ext4. Only used if '''-m data''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 [[BTRFS|btrfs]] xfs.

<code>SYSROOT</code>
:Mountpoint to use when creating volumes and doing traditional disk install ('''-m sys'''). Defaults to {{Path|/mnt}}.

<code>MBR</code>
:Path of MBR binary code, defaults to {{Path|/usr/share/syslinux/mbr.bin}}.

<code>BOOTLOADER</code>
:Bootloader to use, defaults to syslinux. Supported bootloaders are: grub syslinux zipl.

<code>DISKLABEL</code>
:Disklabel to use, defaults to dos. Supported disklabels are: dos gpt eckd.



=== Partitioning ===

If you have complex partitioning needs, that go beyond above alpine-disk options, you can partition, format, and mount your volumes manually, and then just supply the root mountpoint to <code>setup-disk</code>. Doing so implicitly behaves as though '''-m sys''' had also been specified.

See [[Setting up disks manually]] for more information.

==== 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. The array will always be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_1 RAID1] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-0.90_Superblock_Format --metadata=0.90]) for the /boot volumes, but will be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_5 RAID5] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-1_Superblock_Format --metadata=1.2] for non-boot volumes when 3 or more devices are supplied.

If you instead want to build your RAID array manually, see [[Setting up a software RAID array]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.

==== LVM ====
<code>setup-disk</code> will automatically build and use volumes in a LVM group if you supply the '''-L''' switch. The group and volumes created by the script will have the following names:

* volume group: '''vg0'''
* swap volume: '''lv_swap''' (only created when swap size > 0)
* root volume: '''lv_root''' (only created when '''-m sys''' is specified or interactively selected)
* var volume: '''lv_var''' (only created when '''-m data''' is specified or interactively selected)

The '''lv_var''' or '''lv_root''' volumes are created to occupy all remaining space in the volume group.

If you need to change any of these settings, you can use <code>vgrename</code>, <code>lvrename</code>, <code>lvreduce</code> or <code>lvresize</code>.

If you instead want to build your LVM system manually, see [[Setting up Logical Volumes with LVM]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.



 

== setup-lbu ==

This script will only be invoked for by <code>setup-alpine</code> when installing <code>data</code> installation types (ramdisk)

It configures where <code>lbu commit</code> will store the .apkovl backup. See [[Alpine local backup]] for more information.

When started, <code>setup-lbu</code> will prompt where to store your data. The options it will prompt for will be taken from the directories found in <code>/media</code> (except for <code>cdrom</code>). [not sure how these are mounted: are they automatically mounted by setup-lbu? Does the user have to manually mount using another tty?]

 

== setup-apkcache ==

This script will only be invoked for by <code>setup-alpine</code> when installing <code>data</code> installation types (ramdisk)

It configures where to save the apk package files. The apkcache is where apk stores downloaded packages, such that the system does not need to download them again on each reboot, and doesn't have to depend on the network. See [[Local APK cache]] for a detailed explanation.

You should be able to use a partition that you set up in the previous steps.

 

== setup-bootable ==
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

It allows to create boot media that boots the system running from RAM memory (diskless) like the installation images, but using a writable (i.e. not iso9660) filesystem. So that it can also serve to store local customizations (e.g. apkovl files and cached packages).

First, the script copies files from an ISO image (as file on a CD/DVD/USB etc.) onto a USB-Stick/CompactFlash/SDCard etc., or harddisk partition. And then, it installs the syslinux bootloader to make the device bootable.

However, its current syslinux installation seems to fail on non-FAT32 partitions. So in these cases, you may start over with a FAT32 filesystem, or rather with the desired filesystem and using <code>setup-bootable</code> only with the <code>-u</code> option, to skip the syslinux install, and then refer to the [[Create_a_Bootable_Device#Manually_copying_Alpine_files|manual method]] to fix the problem, or use one of the other bootloader options, instead.

{{Tip| The [[Bootloaders]] page shows different ways to setup booting, and multi-boot menus!}}

The setup-bootable script accepts the following arguments and command-line switches (you can run <code>setup-bootable -h</code> to see a usage message).

{{Cmd|setup-bootable <var>source</var> [<var>dest</var>]}}

The argument <var>source</var> can be a directory or an ISO (will be mounted to <code>MNT</code> or {{Path|/mnt}}) or a URL (will be downloaded with <code>WGET</code> or <code>wget</code>). The argument <var>dest</var> can be a directory mountpoint, or will default to {{Path|/media/usb}} if not supplied.

{{Define|-k|Keep alpine_dev in {{Path|syslinux.cfg}}; otherwise, replace with UUID.}}
{{Define|-u|Upgrade mode: keep existing {{Path|syslinux.cfg}} and don't run <code>syslinux</code>}}
{{Define|-f|Overwrite {{Path|syslinux.cfg}} even if '''-u''' was specified.}}
{{Define|-s|Force the running of <code>syslinux</code> even if '''-u''' was specified.}}
{{Define|-v|Verbose mode}}

The script will ensure that <var>source</var> and <var>dest</var> are available; will copy the contents of <var>source</var> to <var>dest</var>, ensuring first that there's enough space; and unless '''-u''' was specified, will make <var>dest</var> bootable.

Suppose the target device is /dev/sdXY, then this partition can be prepared for booting with
{{Cmd|# setup-bootable -v /media/<installation-media-device> /dev/sdXY
}}

For the manual way to set up boot media see [[Create_a_Bootable_Device#Manually_copying_Alpine_files|Manually_copying_Alpine_files]].

 

== setup-xorg-base ==

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

It configures a graphical environment, installing basic Xorg packages and udev (replacing mdev), and is also required for Wayland sessions.

The script installs, among other packages, e.g.: <code>xorg-server xf86-input-libinput xinit udev</code>.

Additional packages to install may be supplied as arguments.
{{cmd|setup-xorg-base [additional package(s) to install]}}

==== Video packages (optional) ====

You may install specific xf86 xorg driver packages for your video card's chipset, as they may support specific features, effects and acceleration modes, and avoid error messages during X initialization.

However, the most basic X features should work fine with just using the default kernel video-modesetting drivers.

Info about the particular video cards that are installed in the computer may be found in the list of PCI devices:
{{cmd|# apk add pciutils
$ lspci}}

To see available video driver packages run:
{{cmd|$ apk search xf86-video}}

For example,
* For an Sis video chipset install 'xf86-video-sis'.
{{Cmd|# apk add xf86-video-sis}}

Others:
* For Intel video chipsets install 'xf86-video-intel' and see [[Intel Video]].
{{Tip|In some cases, freezes on suspend/resume stop happening when changing the video port the monitor is connected to.}}
* For AMD Radeon Video see [[Radeon_Video]]
* For Alix1D use xf86-video-geode.
* In KVM/QEMU guests see [[QEMU#Using_Xorg_inside_Qemu|Xorg within KVM/QEMU]]
* In VirtualBox guests use xf86-video-vboxvideo, and install the [[VirtualBox_guest_additions|VirtualBox guest additions]] as well. They contain important parts for the driver.
* In VMware guests use xf86-video-vmware
* In Hyper-V guests use xf86-video-fbdev and install the [[Hyper-V_guest_services|Hyper-V guest services]] as well.

==== Input packages ====

If the Numlock settings are not working, or getting 'setleds not found' errors:

{{cmd|# apk add kbd}}

If some input device is not working at all, the available xf86-input drivers can be listed with:
{{cmd|$ apk search xf86-input}}

Typical legacy drivers:

{{cmd|# apk add xf86-input-mouse xf86-input-keyboard}}

And for touchpad tapping support on many laptops, also:

{{Cmd|# apk add xf86-input-synaptics}}

==== Configure xorg-server (optional) ====

On most systems, xorg should be able to autodetect all devices. However you can still configure xorg-server by hand by launching:
{{Cmd|# Xorg -configure}}
This will create a `/root/xorg.conf.new` file. You can modify this file to fit your needs. 
(When finished modifying and testing the above configuration file, move it to `/etc/X11/xorg.conf` for normal usage.)

==== Keyboard Layout (optional) ====

If you use a keyboard layout different than "us", and you are using a window manager or desktop environment that does not support to configure the keyboard layout itself, then you need to

* [[Enable_Community_Repository#Using_community_repositories|Enable the "community" repository]]

and install setxkbmap:

{{Cmd|# apk add setxkbmap}}

Then try
# setxkbmap <%a language layout from /usr/share/X11/xkb/rules/xorg.lst%>

In order to make it persistent add this section to /etc/X11/xorg.conf:
{{Cmd|Section "InputClass"
Identifier "Keyboard Default"
MatchIsKeyboard "yes"
Option "XkbLayout" "<%a language layout from /usr/share/X11/xkb/rules/xorg.lst%>"
EndSection
}}

Another way to change the keymap when logging into X is to use ~/.xinitrc. The following example loads a British keymap, simply add this line to the beginning of the file:
<code>setxkbmap gb &</code>

If you need to create the ~/.xinitrc file, you may also want to add a second line like <code>exec openbox-session</code> to still start the window manager with <code>startx</code> or <code>xinit</code>.

 

== Documentation needed ==

=== setup-xen-dom0 ===

 

=== setup-mta ===
Uses ssmtp.

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

 

=== setup-acf ===
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

This script was named <code>setup-webconf</code> before Alpine 1.9 beta 4.

See [[:Category:ACF|ACF pages]] for more information.

= See also =
* [[Installation]]
* [[Alpine newbie]]
* [[Post installation]]

[[Category:Installation]]

Filesystems

2021-12-31T14:18:31Z

Garritfra: /* Install */ Add BTRFS reference

Documentation how to use the Alpine distro to format HD/Floppy/Other.

= Install =
Alpine has multiple storage media formatting packages available. Different packages/programs are used to format different types of filesystems.
* {{Pkg|btrfs-progs}} - For [[BTRFS]]
* {{Pkg|dosfstools}} - For FAT12/FAT16/FAT32
* {{Pkg|e2fsprogs}} - For ext3/ext4
* {{Pkg|f2fs-tools}} - For F2FS
* {{Pkg|jfsutils}} - For JFS
* {{Pkg|ntfs-3g}} - For NTFS (Note: ntfs-3g is a FUSE driver)
* {{Pkg|xfsprogs}} - For XFS

= Format =
Here are some examples on how to use the formatting tools:

{{Note|'''/dev/sda1''' is used as a example}}

==== btrfs-progs ====
{{Cmd|# mkfs.btrfs /dev/sda1}}

==== dosfstools ====
{{Cmd|# mkfs.vfat /dev/sda1}}

==== e2fsprogs ====
{{Cmd|# mkfs.ext2 /dev/sda1}}
{{Cmd|# mkfs.ext3 /dev/sda1}}
{{Cmd|# mkfs.ext4 /dev/sda1}}

==== f2fs-tools ====

{{Cmd|# mkfs.f2fs /dev/sda1}}

= Partitions =
If you need to change or make a partition table on a Hard Drive you want to format, you can use:

==== fdisk ====
{{Cmd|# fdisk /dev/sda}}

==== cfdisk ====
{{Cmd|# cfdisk /dev/sda}}

[[Category:Storage]]

Alpine Package Keeper

2021-12-31T14:17:51Z

Garritfra: Add reference to BTRFS page

{{TOC right}}

Because Alpine Linux is designed to run from RAM, package management involves two phases:
* Installing / Upgrading / Deleting packages on a running system.
* Restoring a system to a previously configured state (e.g. after reboot), including all previously installed packages and locally modified configuration files. '''(RAM-Based Installs Only)'''
 
'''apk''' is the tool used to install, upgrade, or delete software on a running system. 
'''lbu''' is the tool used to capture the data necessary to restore a system to a previously configured state.

This page documents the [https://git.alpinelinux.org/apk-tools/ apk tool] - See the [[Alpine_local_backup|Alpine Local Backup page]] for the lbu tool.

= Overview =

The '''apk''' tool supports the following operations:

{|
| [[#Add a Package|add]]
| Add new packages or upgrade packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| fix
| Attempt to repair or upgrade an installed package
|-
| [[#Update the Package list|update]]
| Update the index of available packages
|-
| [[#Information on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|-
| dot
| Create a [http://graphviz.org/ graphviz] graph description for a given package
|-
| [[#apk_policy|policy]]
| Display the repository that updates a given package, plus repositories that also offer the package
|-
| stats
| Display statistics, including number of packages installed and available, number of directories and files, etc.
|-
| manifest
| Display checksums for files contained in a given package
|}

= Packages and Repositories =

Software packages for Alpine Linux are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata. They have the extension <code>.apk</code>, and are often called "a-packs".

The packages are stored in one or more ''repositories''. A repository is simply a directory with a collection of *.apk files. The directory must include a special index file, named {{Path|APKINDEX.tar.gz}} to be considered a repository.

The '''apk''' utility can install packages from multiple repositories. The list of repositories to check is stored in {{Path|/etc/apk/repositories}}, one repository per line. If you booted from a USB stick ({{Path|/media/sda1}}) or CD-ROM ({{Path|/media/cdrom}}), your repository file probably looks something like this:

{{Cat|/etc/apk/repositories|/media/sda1/apks/}}

In addition to local repositories, the '''apk''' utility uses '''busybox wget''' to fetch packages using ''http:'', ''https:'' or ''ftp:'' protocols. The following is a valid repository file:

{{Cat|/etc/apk/repositories|
/media/sda1/apks
http://dl-3.alpinelinux.org/alpine/v2.6/main
https://dl-3.alpinelinux.org/alpine/v2.6/main
ftp://dl-3.alpinelinux.org/alpine/v2.6/main
}}

{{Note| A list of public repositories is in [https://mirrors.alpinelinux.org/ mirrors.alpinelinux.org]. Accepted protocols vary.}}

== Repository pinning ==

You can specify additional "tagged" repositories in {{Path|/etc/apk/repositories}}:

{{Cat|/etc/apk/repositories|
http://nl.alpinelinux.org/alpine/v3.7/main
http://nl.alpinelinux.org/alpine/v3.7/community
@edge http://nl.alpinelinux.org/alpine/edge/main
@edgecommunity http://nl.alpinelinux.org/alpine/edge/community
@testing http://nl.alpinelinux.org/alpine/edge/testing
}}

After which you can "pin" dependencies to these tags using:

{{cmd|apk add stableapp newapp@edge bleedingapp@testing}}

Apk will now by default only use the untagged repositories, but adding a tag to specific package:

1. will prefer the repository with that tag for the named package, even if a later version of the package is available in another repository

2. ''allows'' pulling in dependencies for the tagged package from the tagged repository (though it ''prefers'' to use untagged repositories to satisfy dependencies if possible)

== Commandline repository options ==

By default, the '''apk''' utility will use the system repositories for all operations. This behavior can be overridden by the following options:

{|
| --repositories-file REPOFILE
| Override the system repositories by specifying a repositories file.
|-
| <nowiki>-X|--repository REPO</nowiki>
| Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.
|}

= Update the Package list =

Remote repositories change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. The command downloads the {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/cache/apk/}}, {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}.

{{Cmd|apk update}}



Adding the <code>--update-cache</code>, or for short <code>-U</code> switch to another apk command, as in <code>apk --update-cache upgrade</code> or <code>apk -U add ...</code>, the command has the same effect as first running <code>apk update</code> before the other apk command.

{{Tip|With remote repositories, it is a good idea to always do an '''update''' right '''before''' doing an '''upgrade or add''' command. That way the command will install the latest available packages.}}

= Add a Package =

Use '''add''' to install packages from a repository. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package.

{{Cmd|apk add openssh
apk add openssh openntp vim}}

If you only have the main repository enabled in your configuration, apk will not include packages from the other repositories. To install a package from the edge/testing repository without changing your repository configuration file, use the command below. This will tell apk to use that particular repository.

{{cmd|apk add cherokee --update-cache --repository http://dl-cdn.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

{{Note|Be careful when using third-party or the testing repository. Your system can go down.}}

= Add a local Package =

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the '''--allow-untrusted''' flag:

{{cmd|apk add --allow-untrusted /path/to/file.apk}}

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

{{cmd|apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk}}

= Remove a Package =
Use '''del''' to remove a package (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

= Upgrade a Running System =

=== Packages in general ===

To get the latest security upgrades and bugfixes available for the ''installed'' packages of a running system, first '''update''' the list of available packages and then '''upgrade''' the installed packages:

{{cmd|apk update
apk upgrade
}}

Or, combining the same into one single command:

{{cmd|apk -U upgrade
}}

Here is an example, showing the procedure on a system that has several additional [[#Repository_pinning|repositories pinned]]:

# apk update
fetch <nowiki>http://dl-3.alpinelinux.org/alpine/v3.6/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>http://dl-3.alpinelinux.org/alpine/v3.6/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>http://dl-3.alpinelinux.org/alpine/edge/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>http://dl-3.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>http://dl-3.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz</nowiki>
v3.6.2-191-gf98d79930f <nowiki>[http://dl-3.alpinelinux.org/alpine/v3.6/main]</nowiki>
v3.6.2-190-ga5d68c47df <nowiki>[http://dl-3.alpinelinux.org/alpine/v3.6/community]</nowiki>
v3.6.0-4618-g0bf77c9821 <nowiki>[http://dl-3.alpinelinux.org/alpine/edge/main]</nowiki>
v3.6.0-4605-g85ed51dd83 <nowiki>[http://dl-3.alpinelinux.org/alpine/edge/community]</nowiki>
v3.6.0-4624-g11f1b9c8ab <nowiki>[http://dl-3.alpinelinux.org/alpine/edge/testing]</nowiki>
OK: 20118 distinct packages available

# apk upgrade
(1/2) Upgrading extra-cmake-modules@testing (5.38.0-r0 -> 5.39.0-r0)
(2/2) Upgrading extra-cmake-modules-doc@testing (5.38.0-r0 -> 5.39.0-r0)
Executing mdocml-apropos-1.14.1-r0.trigger
OK: 2635 MiB in 803 packages

To upgrade only ''specific'' packages, use the ''-u'' or ''--upgrade'' option of the '''add''' command:

{{cmd|apk update
apk add --upgrade busybox
}}

To enable unattended, automatic upgrades of packages, see the {{pkg|apk-autoupdate}} package.

To upgrade to a newer release, refer to the corresponding release notes and [[Upgrading_Alpine]].

=== Upgrading "diskless" and "data" disk mode installs ===

If booting a "diskless" system from a read-only device, or iso image on writable media, it's not possible to update the boot files (kernel, modules, firmware, ...) that reside on that device.

It becomes possible to update the boot files, though, if using a boot device that is writable and has been prepared with <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code>.

However, even then, the kernel, with its modules and firmware files, can still not be updated directly through regular packages updates. Instead, there is the <code>update-kernel</code> script that can generate initfs images and install them together with upgraded kernels.

Upgrading can be done as follows.
{{cmd|apk add mkinitfs
}}
This package is required for the generation of the initial filesystem used during boot.
* Additional initfs features that are missing in the default configuration, like the [[BTRFS|btrfs]] filesystem support (at the time of writing, to allow loading .apkovl configs and package cache during boot), may be enabled in <code>/etc/mkinitfs/mkinitfs.conf</code>.
* Available initfs features may be listed with <code>ls /etc/mkinitfs/features.d</code>
{{cmd|ls /etc/mkinitfs/features.d
apk add nano
nano /etc/mkinitfs/mkinitfs.conf
lbu commit
}}
Finally update the kernel and its boot environment.
{{cmd|update-kernel /media/sdXY/boot/
}}
* An <code>update-kernel</code> run needs at least 8 GB free ram memory to avoid a broken modloop-image.
* See <code>update-kernel --help</code> for options to manually add additional module or firmware packages.

= Search for Packages =
The '''search''' command searches the repository Index files for installable packages.

The return format is '''Package'''-'''Version'''. Omit '''Version''' for ''apk add '''Package'''''

Examples:
* To list all packages available, along with their descriptions: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|apk search -v --description 'NTP' }}

= Information on Packages =

== apk info ==

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information), or all information displayed with the ''-a'' command.

Example: {{cmd|apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>http://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

{{Tip|The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|apk info --who-owns /sbin/lbu}} will display

/sbin/lbu is owned by alpine-conf-x.x-rx
}}

=== Listing installed packages ===

To list all installed packages, use:

<pre>apk info</pre>

To list all installed packages in alphabetical order, with a description of each, do:

<pre>apk -vv info|sort</pre>

The apk tool does not have a subcommand to list manually-installed packages that do not have reverse dependencies. To get this information on a traditional system that is not using [[Alpine local backup|lbu]], try this script. Note that this approach will also list core packages like alpine-base that should not be removed.

<pre>#!/bin/sh
apk info | grep -ve '-doc$' | sort | while read pkg
do
rdep=`apk info -qr "$pkg"`
[ -z "$rdep" ] && echo $pkg
done</pre>

== apk policy ==

To display the repository a package was installed from and will be updated from, plus any [[#Repository_pinning|tagged]] or enabled repositories where it is also offered, if any, for this architecture - its '''policy''':

apk policy ''package''

For example:
<pre>
$ apk policy vlc
vlc policy:
2.2.6-r1:
lib/apk/db/installed
http://dl-3.alpinelinux.org/alpine/v3.7/community
3.0.0_rc2-r1:
@edgecommunity http://dl-3.alpinelinux.org/alpine/edge/community
</pre>

= Additional apk Commands =
In progress...

= Local Cache =

{{:Local_APK_cache}}

= Advanced APK Usage =

== Holding a specific package back ==

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

will upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

will ensure that 1.6.1 is the minimum version used.

You can also use "fuzzy" version matching to pin the version to a major/minor release. For example:

{{cmd|1=apk add 'asterisk=~1.6'}}

will match any version of asterisk that starts with 1.6 (such as 1.6.0.21-r0 or 1.6.9.31-r9) <ref>[https://git.alpinelinux.org/apk-tools/commit/?id=693b4bcdb0f22904a521a7c8ac4f13e697dc4d71 Alpine source commit message]</ref>

If you desire deterministic, repeatable package installation (such as with containerized environments) via package pinning, it is important to understand your package repo's version retention rules. For example, most Alpine package repos contain an "edge" branch, which may drop package versions that are not deemed fit to make it into a stable branch. This means that pinning to a version on the edge branch may stop working after the package version is revoked from the repo. Always pin to a package version that is intended for your current Alpine Linux version.

= Troubleshooting =

== "apk-tools is old" ==

'''apk update''', '''apk upgrade''' or '''apk add''' may report the following:
WARNING: This apk-tools is OLD! Some packages might not function properly

This may happen if you are running Alpine Linux stable version with a certain edge/main, edge/community or testing package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge is already [https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management#Repository_pinning tagged] in your repositories, then try:

<pre>sudo apk add --upgrade apk-tools@edge</pre>

= External Links =
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples] Vivek Gite 2019

[[Category:Package Manager]]

Btrfs

2021-12-31T14:14:46Z

Garritfra: Add BTRFS entry

Documentation how to use BTRFS on Alpine Linux.

== Install ==

Installing [https://de.wikipedia.org/wiki/Btrfs BTRFS] is relatively straight forward. Install the package and tell Alpine to load the module on startup:

{{Cmd|apk add btrfs-progs
echo btrfs >> /etc/modules}}

To load the module right away, you can use the following command:

{{Cmd|modprobe btrfs}}

== Mounting a volume ==

To mount a volume on boot, add a new entry to your fstab:

UUID=abcdef-0055-4958-990f-1413ed1186ec /var/data btrfs defaults,nofail,subvol=@ 0 0

More information about mounting can be found in the official [https://btrfs.wiki.kernel.org/index.php/Main_Page BTRFS wiki]

== Troubleshooting ==

=== Mount failed ===

If you try mounting a btrfs volume via your /etc/fstab and it doesn't show up, it could be because BTRFS does not know about the drives during boot.

To work around this, you can create an OpenRC service that runs a ''btrfs scan'' to detect the drives. To do so, create a new service under /etc/init.d/btrfs-scan with the following content:

#!/sbin/openrc-run

name="btrfs-scan"

depend() {
before localmount
}

start() {
/sbin/btrfs device scan
}

Make the service executable and register it:

{{Cmd|chmod +x /etc/init.d/btrfs-scan
rc-update add btrfs-scan boot
}}

The volume should mount correctly after a reboot.

== Other Resources ==

# [https://garrit.xyz/posts/2021-12-31-btrfs-on-alpine BTRFS on Alpine Linux]
# [https://nparsons.uk/blog/using-btrfs-on-alpine-linux Using BTRFS on Alpine Linux]
# [https://gitlab-test.alpinelinux.org/alpine/aports/-/issues/9539 Can't mount BTRFS volume using fstab]