VPS on Charlie Chiang's blog

Building Alpine Linux Disk Images Without a VM

Sat, 05 Sep 2026 22:00:00 +0800

In Minimal Alpine Linux on a 1 GB Btrfs Root Disk I wrote down the recipe I use to build a tiny Alpine instance: boot the ISO in a VM, run setup-alpine with disk=none, partition by hand, setup-disk -m sys /mnt, reboot, then qemu-img convert the disk. It works, and I still use that post as the explanation of why the pieces are the way they are.

What I got tired of is the process. Every image costs a VM, a console session, and a sequence of interactive answers, and none of it is reproducible: if I want the same image with ext4 instead of btrfs, I do the whole thing again and hope I remember every step.

So I replaced it with a script. It builds the disk image as a file, on any Linux host, with no VM and no prompts. It also fixes the two things I did not like about the old recipe: the image now boots under both BIOS and UEFI, and every choice is configurable.

The bundle for this post contains everything:

mkalpine.sh — the builder
config.example.sh — every knob with comments
testboot.sh — boot the result under QEMU and check it came up
testmatrix.sh — build and boot every supported combination
hooks/ — the customizations, one file each

1

sudo ./mkalpine.sh -f alpine.img

That is the whole interface. About a minute later there is a 512 MiB sparse image, 102 MiB of it actually allocated, that boots on either firmware. The image is deliberately small — 70-growroot expands the root filesystem to fill whatever disk it lands on, so IMAGE_SIZE only has to hold the build.

Why No VM Is Needed

The manual recipe suggests that installing Alpine requires a running Alpine. It does not. Once you look at what the installer actually does, almost all of it is file manipulation:

Unpack a root filesystem.
apk add a kernel, an initramfs generator, and a bootloader.
Write /etc/fstab, /etc/inittab, and the network config.
Run mkinitfs and grub-install.
Enable some OpenRC services, which is ln -s in a directory.

Only steps 2 and 4 need to execute Alpine binaries, and a chroot is enough for that. There is no step that needs a booted kernel, a real block device, or firmware.

Alpine’s own setup-disk cannot be reused here, unfortunately. It sources libalpine.sh, calls lbu package, and assumes throughout that it is running on a booted live system. So mkalpine.sh reimplements the same steps directly, following the structure of upstream alpine-make-vm-image and the bootloader logic from setup-disk.

The pipeline is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


truncate -s 512M image create a sparse file
sfdisk partition it
losetup -P get /dev/loopNp1..p3
mkfs.vfat / mkfs.btrfs make filesystems
mount mount root, then /boot inside it
tar -x minirootfs unpack the base system
chroot + apk add kernel, mkinitfs, grub, fs tools
mkinitfs / grub-install bootloader for both firmwares
hooks/ customizations
fstrim; umount; losetup -d compact and release
qemu-img / zstd / gzip optional output formats

QEMU is not needed to build. It is used only for qcow2 output and by the boot tests.

One line of that pipeline is less innocent than it looks. losetup -P asks the kernel to scan the partition table, but the /dev/loopNp* nodes are created by udev, after losetup has already exited, so they have to be waited for — and on a host with no udev at all, such as a container whose /dev is a plain tmpfs, they have to be created by hand from the device numbers the kernel publishes in /sys/block/loopN/loopNpM/dev. Both paths are in the script, and the interesting part is the order they are tried in: reaching for mknod early is a mistake, because when udev gets round to the same events it unlinks your node and makes its own, and for the instant in between the path does not exist. On a test host, that instant landed exactly on mkfs.vfat:

1

mkfs.vfat: unable to open /dev/loop0p2: No such file or directory

So the escalation is now slow on purpose — udevadm settle, a second, partx -a, another second, and only then mknod — and once the nodes do appear there is one more settle before anything opens them, so a replacement in flight finishes before mkfs runs rather than during it.

The Disk Layout

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


GPT (default; the protective MBR still carries GRUB's boot.img)

 # size type mount contents
 1 1 MiB ef02 BIOS boot - grub core.img (x86_64 only)
 2 64 MiB ef00 ESP FAT32 /boot vmlinuz-virt, initramfs-virt,
 grub/, EFI/BOOT/BOOTX64.EFI
 3 rest L Linux / btrfs (default), ext4 or xfs

BIOS : firmware -> MBR boot.img -> p1 core.img -> /boot/grub/grub.cfg
UEFI : firmware -> p2 /EFI/BOOT/BOOTX64.EFI -> /boot/grub/grub.cfg

Two details are worth calling out.

/boot is the ESP. This is not just to save a partition. It means GRUB only ever has to read FAT. Btrfs, ext4 and XFS roots all work without GRUB parsing them at all, and no on-disk feature the root filesystem gains later can break the bootloader. The old post used Syslinux on ext4 /boot; this is less fragile.

GRUB is installed to the removable path. grub-install --removable --no-nvram writes EFI/BOOT/BOOTX64.EFI (or BOOTAA64.EFI), which is what firmware boots when NVRAM has no entry for the disk. We cannot write the target machine’s NVRAM from a build host anyway, and cloud firmware is generally starting from a blank slate.

On aarch64 the BIOS partition is omitted and only UEFI is set up: Alpine ships grub-efi for arm64 but there is no grub-bios, because the i386-pc target is x86-only.

The MBR Variant

Some providers’ image import still rejects GPT. PARTITION_TABLE=mbr handles that:

1
2
3
4
5
6
7


DOS/MBR

 # start type mount contents
 - sector 0 MBR + gap - grub boot.img (sector 0) and
 core.img (the ~1 MiB gap before p1)
 1 2048 0xEF, bootable /boot same as above
 2 after p1 0x83 / root

No dedicated BIOS boot partition is needed, because GRUB’s i386-pc target embeds core.img in the gap between the MBR and the first partition — which is about 1 MiB, given the 2048-sector start. UEFI still works on most firmware, since the ESP is located by partition type 0xEF. That is a widely followed convention rather than something the spec promises, so MBR mode is “BIOS guaranteed, UEFI very likely”, and GPT stays the default.

What It Trusts

The bootstrap is a single alpine-minirootfs tarball, resolved from latest-releases.yaml for the branch:

TLS gets the file from the mirror.
Alpine publishes a .sha256 sidecar next to every release artifact. The build fails and deletes the download on a mismatch.
Everything after that is apk, with Alpine’s signing keys, from the tarball’s own keyring.

I use the minirootfs rather than a pinned apk.static deliberately: a hardcoded apk.static checksum drifts out of sync with the branch, and the in-image apk always matching the branch matters now that 3.23+ ships apk-tools 3.

ALPINE_BRANCH=latest-stable is the default and gets resolved once, at build time. The repositories written into the image always point at the concrete branch (v3.24), never at latest-stable, so a later apk upgrade on the running machine does not silently jump to the next stable release.

Configuration

Copy the example and edit it; ./config.sh is picked up automatically.

1
2
3


cp config.example.sh config.sh
$EDITOR config.sh
sudo ./mkalpine.sh

Every variable is : "${VAR:=default}" in the script, so the environment works too, which is what I use for one-offs:

1

sudo IMAGE_SIZE=2G ROOT_FS=xfs ./mkalpine.sh out.img

Secrets default to nothing. ROOT_PASSWORD_HASH="" locks the root account, so the failure mode of forgetting to set it is “cannot log in”, not “known root password”, and the example hash ships commented out next to the openssl passwd -6 that generates one. config.sh and the image files are in .gitignore.

If the build host reaches the internet through a proxy, an exported http_proxy / https_proxy / no_proxy is picked up as-is, and BUILD_HTTP_PROXY / BUILD_HTTPS_PROXY / BUILD_NO_PROXY set one for the build alone. It covers both halves of the download: the minirootfs tarball on the host, and apk plus whatever a hook fetches inside the chroot. Both cases of each name are set in the chroot’s environment, because curl reads only the lowercase http_proxy while apk and git take either — and they go into the environment rather than a profile script, so nothing about the proxy survives into the image. A proxy reachable from the build host is usually not reachable from wherever the image is deployed, and the URL frequently carries credentials.

Choosing A Root Filesystem

ROOT_FS takes btrfs, ext4 or xfs, each with its own mkfs and mount option strings:

`ROOT_FS`	`ROOT_MKFS_OPTS`	`ROOT_MOUNT_OPTS`
`btrfs`	`-L alpine-root -K`	`rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2`
`ext4`	`-L alpine-root -m 1 -E nodiscard`	`rw,noatime,commit=60`
`xfs`	`-L alpine-root`	`rw,noatime,logbsize=256k`

-K and -E nodiscard skip the discard pass at mkfs time, which is pointless on a sparse file and only produces confusing errors.

Btrfs with zstd stays the default for the same reason as in the old post — on a small disk, transparent compression is worth a lot.

Tuning mkfs For The Storage Underneath

The point of exposing ROOT_MKFS_OPTS is that a cloud disk is rarely a plain disk. config.example.sh carries these examples.

Aligning to a 16 KiB ZFS zvol (volblocksize=16k):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# ext4: the block size cannot exceed the kernel page size (4 KiB on x86_64),
# so -b 16384 produces a filesystem that will not mount. Align with
# stride/stripe_width instead: stride = 16K / 4K = 4.
ROOT_MKFS_OPTS="-L alpine-root -m 1 -E nodiscard,stride=4,stripe_width=4"

# or, if you really do want 16 KiB allocation clusters:
ROOT_MKFS_OPTS="-L alpine-root -m 1 -O bigalloc -C 16384"

# xfs: takes the stripe unit directly.
ROOT_MKFS_OPTS="-L alpine-root -d su=16k,sw=1"

# btrfs: nodesize is already 16K; set the sector size explicitly if the host
# page size differs from the target's.
ROOT_MKFS_OPTS="-L alpine-root -K -s 4096"

Aligning to RAID6 with 6 data disks and a 128 KiB chunk:

1
2
3
4
5
6


# ext4: stride = chunk / block = 128K / 4K = 32
# stripe_width = stride * data disks = 32 * 4 = 128
ROOT_MKFS_OPTS="-L alpine-root -m 1 -E nodiscard,stride=32,stripe_width=128"

# xfs: su = chunk, sw = number of data disks
ROOT_MKFS_OPTS="-L alpine-root -d su=128k,sw=4"

Tuning Mount Options

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Favour throughput over sync latency. You lose more recent writes on an
# unclean shutdown, which is fine for a rebuildable instance and not fine
# for a database.
ROOT_MOUNT_OPTS="rw,noatime,commit=60,data=writeback" # ext4
ROOT_MOUNT_OPTS="rw,noatime,logbsize=256k,allocsize=1m" # xfs
ROOT_MOUNT_OPTS="rw,noatime,commit=120,compress=zstd:1,ssd,discard=async,space_cache=v2"

# Favour density on a tiny disk. zstd:6 costs CPU on write; decompression
# stays cheap at any level.
ROOT_MOUNT_OPTS="rw,noatime,compress=zstd:6,ssd,discard=async,space_cache=v2"

# Drop discard=async and rely on the weekly fstrim job instead, if your
# provider's thin pool behaves badly with continuous discards.
ROOT_MOUNT_OPTS="rw,noatime,compress=zstd:3,ssd,space_cache=v2"

These options are used to mount the image during the build as well as being written to /etc/fstab, so a typo fails the build instead of the first boot. There is exactly one deliberate difference between the two, and it is the subject of Compression Needs Forcing At Build Time below.

The Mount Option Gotcha

This one cost me a while, and it is the reason the boot test in the bundle checks mount options rather than trusting them.

ROOT_MOUNT_OPTS in /etc/fstab is not enough. The root filesystem is mounted by the initramfs, long before /etc/fstab exists, and the mount -o remount,rw / that OpenRC does afterwards cannot change every option. Most are remountable, so noatime and commit=60 looked fine. XFS, however, fixes the log buffer size at initial mount:

1
2
3
4
5


# what I asked for
ROOT_MOUNT_OPTS="rw,noatime,logbsize=256k"

# what the running machine actually had
rw,noatime,inode64,logbufs=8,logbsize=32k,noquota

Silently downgraded to the 32k default, with nothing in dmesg about it. Mounting the same image on the build host with the same options honoured logbsize=256k, which made it look like a kernel difference rather than what it was.

The fix is to put the options on the kernel command line too, so that the initial mount is the one I want:

1
2
3


ROOTFLAGS=$(echo "$FSTAB_ROOT_OPTS" | tr ',' '\n' |
 grep -vx -e rw -e ro | tr '\n' ',' | sed 's/,*$//')
[ -n "$ROOTFLAGS" ] && CMDLINE="$CMDLINE rootflags=$ROOTFLAGS"

rw and ro are dropped because the kernel handles those separately and GRUB already passes ro. With Btrfs you end up with two rootflags= on the cmdline, because grub-mkconfig’s 10_linux detects the subvolume and emits its own; ours is appended after GRUB’s and the initramfs takes the last one.

Now:

1

rw,noatime,inode64,logbufs=8,logbsize=256k,noquota

Btrfs Subvolumes

BTRFS_SUBVOL="@" by default. It costs three lines at build time, and retrofitting a root subvolume later means moving every file, so it is worth doing even on a machine too small to keep many snapshots. Compression is also set with btrfs property set, so it holds regardless of mount options. BTRFS_SUBVOL="" gives the top-level layout from the old post. GRUB does not care either way, because /boot is FAT.

Compression Needs Forcing At Build Time

compress=zstd:3 does not compress everything. Btrfs decides per file, from the beginning of the file, whether compressing is worth it — and on ELF binaries it decides wrong. In a default build, 45 MiB out of 83 MiB was stored uncompressed, including libcrypto.so.3 (3.3 MiB), every grub-* tool, busybox and ld-musl. All of those compress to roughly half. btrfs property set does not help here either: a file carrying only the inode flag still goes through the same heuristic.

compress-force skips the decision. The build mounts the root with it, while /etc/fstab and rootflags= keep plain compress=:

1
2


BUILD_ROOT_OPTS=$(printf '%s' "$ROOT_MOUNT_OPTS" |
 sed 's/^compress=/compress-force=/; s/,compress=/,compress-force=/')

That is the one place where what the build mounts deliberately differs from what the image ships. It takes 62 MiB of data on disk down to 56 MiB, the raw image from 108 MiB to 102 MiB, and df on the booted machine from 74.5 MiB used to 67.9 MiB; BTRFS_FORCE_COMPRESS=no restores the old behaviour. The build prints what it achieved —

1

root data 55M on disk for 86M of files (64%)

— because the answer depends on what the image installs, and the failure mode is otherwise silent: the mount options, and findmnt, look exactly the same whether the files got compressed or not.

The heuristic is left alone for the running system on purpose. It exists to avoid burning CPU on data that will not compress, and this image contains about 10 MiB of exactly that: Alpine ships kernel modules as .ko.gz, and xfs.ko.gz, btrfs.ko.gz and friends stay uncompressed whether you force it or not. Forcing only recovers the files the heuristic misjudged.

Running btrfs filesystem defragment -r -czstd over the finished tree is the other way to get here, and it is the worse one. It lands at 58 MiB rather than 56 MiB, the sparse image balloons to 168 MiB before fstrim claws it back, and despite the name it does not defragment anything — compressed extents cap at 128 KiB, so the extent count went up, 1996 → 2082.

One caveat if you ship a compressed artifact rather than the raw image: compressing inside the image makes the outer compressor’s job harder, and the outer compressor is better at it. Forcing shrank the raw image by 5.6% and grew every compressed output — raw.zst 74 → 77 MiB, raw.xz 72 → 76 MiB. If upload size is the thing you actually care about, BTRFS_FORCE_COMPRESS=no is the right setting, and the build says as much when you ask for both.

Sizing `/boot`

BOOT_SIZE=64M. Measured usage with one kernel is 36 MiB:

1
2
3
4
5
6


13 M vmlinuz-virt
9.4M initramfs-virt
8.3M grub/ (i386-pc and x86_64-efi modules)
6.2M System.map-6.18.48-0-virt
156K EFI/BOOT/BOOTX64.EFI
149K config-6.18.48-0-virt

That leaves headroom for one kernel and no more. Raise it to 128M if you want to keep a second kernel around — linux-lts alongside linux-virt, say — or if you want the previous kernel to survive an apk upgrade so there is something to fall back to. The build prints /boot usage at the end and warns when it lands above 80%.

Output Formats

OUTPUT_FORMATS is a space-separated list; each entry produces one file next to the raw image.

Entry	Produced by	Size	Note
`raw`	the build itself	102 MiB	sparse; 512 MiB apparent
`qcow2`	`qemu-img convert -c -O qcow2`	81 MiB	compressed qcow2
`raw.zst`	`zstd -19 -T0`	77 MiB	best ratio for the time; widely accepted
`raw.gz`	`gzip -9`	80 MiB	widest provider support
`raw.xz`	`xz -9 -T0`	76 MiB	smallest, slowest

The sizes are from one build of the same default btrfs image, so they are comparable to each other rather than absolute. Note how little the four compressed formats differ — 76 to 81 MiB, under 7% between the best and the worst: the root filesystem is already zstd-compressed, so the outer compressor is mostly squeezing free space. raw.gz is a perfectly reasonable default in exchange for its compatibility.

That is also why BTRFS_FORCE_COMPRESS cuts the other way here. Every one of these numbers except qcow2 is larger than it would be with forcing off — raw.xz most of all, 76 MiB against 72 MiB — because data that btrfs already compressed at zstd:3 in 128 KiB blocks is data xz -9 cannot compress again. Forcing wins on raw and loses on everything else, so the build prints a reminder when you ask for both.

Drop raw from the list to keep only the compressed artifacts. For other hypervisors, convert the raw image yourself:

1
2
3


qemu-img convert -O vmdk out.img out.vmdk # VMware
qemu-img convert -O vpc out.img out.vhd # Hyper-V / Azure
qemu-img convert -O vdi out.img out.vdi # VirtualBox

What Must Not Survive Cloning

A disk image is a template that gets cloned N times, so anything unique baked into it stops being unique. This is the part a hand-built VM image usually gets wrong, and it is why I wanted a script in the first place — I am not going to remember all of this at 1am on a provider’s web console.

Thing	Why it matters	What the script does
`/etc/ssh/ssh_host_*`	Every VM built from the image shares one host key. Anyone holding the image can impersonate all of them, and clients get key-mismatch warnings after the first deploy.	Delete. Regenerated on first boot.
`/var/lib/seedrng/seed.credential` (3.17+; `/var/lib/random-seed` before)	The saved RNG seed is restored early at boot. An identical seed on every clone means the entropy pool starts identical — including for the host keys in the row above.	Delete.
`/etc/machine-id`	Used to derive DHCP DUIDs and app-level instance identity, so clones can collide on DHCP leases.	Truncate to zero bytes, not delete: an empty file is the documented “generate on next boot” signal, while a missing one makes some tools fail instead.
`/etc/resolv.conf`	Would otherwise ship the build host’s nameservers.	Rewritten from `$DNS`.
`/var/cache/apk/`, `/var/log/`, shell history	Dead weight and build-host leakage.	Cleared.

Filesystem UUIDs do stay identical across clones. Regenerating them on first boot means rewriting fstab and grub.cfg from a running system, which is more fragile than the problem it solves — it only bites if you attach two clones to the same host.

The 80-firstboot hook is the other half of this. It runs in the boot runlevel, before networking and sshd, and generates what was stripped:

1
2


head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n' >/etc/machine-id
ssh-keygen -A

It also runs after hostname, so the host keys are commented root@alpine rather than root@(none). Cosmetic, but the alternative bothered me.

Finally, the build stamps /etc/image-release with the Alpine version, architecture, build date, builder git commit, and the resolved filesystem and hook configuration. Six months later, working out which build a running VM came from is otherwise guesswork.

Staying Able To Get In

The single most valuable property of a cloud image is that you can get into it when networking is broken, because the provider’s serial console is then your only channel.

console=ttyS0,115200 on x86_64, console=ttyAMA0,115200 on aarch64, with the getty in /etc/inittab and the tty listed in /etc/securetty. Without the securetty entry, root login on that console is refused and looks exactly like a wrong password.
GRUB_TERMINAL="console serial" plus GRUB_SERIAL_COMMAND, so the bootloader is reachable over serial too. That is what lets you fix a bad kernel cmdline or boot an older kernel remotely.
No quiet. Alpine’s setup-disk defaults to KERNELOPTS=quiet; on a machine whose only debugging channel is the serial console, hiding the boot log is the wrong trade.
GRUB_TIMEOUT=1 rather than 0, so there is a window to interrupt.

grub.cfg is generated by grub-mkconfig rather than hand-written, which matters more than it looks: Alpine’s grub package carries triggers="grub.trigger=/boot", so a later apk upgrade linux-virt regenerates it and the image stays bootable with no intervention. A static config would just be silently overwritten by that same trigger. There is a hand-written fallback for the case where grub-probe cannot cope with the loop device, but I have not needed it.

Hooks

One ordered list, in HOOKS. Remove a name to disable it; drop a file into hooks/ and add its name to extend. Each hook is a standalone sh script run inside the chroot with the configuration exported into its environment.

1

HOOKS="10-network 20-ssh 30-chrony 40-zram 50-logtruncate 60-sysctl 70-growroot 80-firstboot"

Hook	Does
`10-network`	`/etc/network/interfaces`, DHCP or static, optional real DHCPv6
`20-ssh`	`PermitRootLogin`, port, keepalives, `authorized_keys`
`30-chrony`	chrony with `makestep 1.0 -1` and a configurable pool
`40-zram`	zram swap sized from RAM at boot, optionally `/tmp` too
`50-logtruncate`	the hourly log cap from the old post, plus a daily apk cache clean
`60-sysctl`	zram VM tunables, BBR and fq
`70-growroot`	one-shot service: `growpart`, then grow the filesystem
`80-firstboot`	machine-id and SSH host key generation

Off by default, because they are opinionated rather than essential: 90-tools (bash, coreutils, iproute2, tcpdump, htop, tmux, vim and friends — about 120 MiB), 91-ufw, 92-sshguard, 93-podman, 94-cloud-init, and 95-dotfiles (git, zsh, lsd and a dotfiles repo, with zsh as root’s login shell).

91-ufw, 92-sshguard and 95-dotfiles are cheap enough to add at the default IMAGE_SIZE on any filesystem. The heavier three are where the compression default starts paying for itself: 90-tools + 93-podman + 94-cloud-init together fit on btrfs at 512 MiB — 274 MiB allocated — and run the 381 MiB XFS root out of space partway through installing podman. Raise IMAGE_SIZE if you want them on ext4 or XFS.

A few implementation notes:

20-ssh rewrites existing lines rather than appending. sshd_config takes the first occurrence of a keyword, so appending PermitRootLogin prohibit-password to a file that already contains a commented-out default works, and appending it to one that has an active setting silently does nothing. The hook edits in place.

50-logtruncate truncates rather than renames. Keeping one .0 copy and then truncate -s 0 on the original preserves the inode, so daemons holding the file open keep writing to it. This is the script from the old post, unchanged.

70-growroot uses growpart, not sfdisk. Growing a GPT disk also requires relocating the backup header to the new end of the device, and growpart keeps the partition’s start sector untouched, so whatever alignment the image was built with survives. After that it is btrfs filesystem resize max /, resize2fs or xfs_growfs depending on ROOT_FS, then a stamp file and rc-update del growroot default.

91-ufw exploits the fact that ufw only touches netfilter when enabled. All the rules are recorded inside the chroot with ufw itself, and then ENABLED=yes is set in ufw.conf as the last step. No netfilter calls happen during the build.

95-dotfiles is the only hook that needs the network for something other than the Alpine mirror. It shallow-clones DOTFILES_REPO, runs the repo’s own bootstrap.sh, and switches root’s login shell. Two parts of that were more interesting than expected.

Changing the login shell, first: chsh is not in a minimal Alpine — it lives in shadow, which nothing else here wants — so the hook rewrites field 7 of root’s /etc/passwd line directly. Writing the new file elsewhere and cat-ing it back keeps the original inode, mode and owner, which a mv would not:

1
2
3


awk -F: -v OFS=: -v shell="$login_shell" \
 '$1 == "root" { $7 = shell } { print }' /etc/passwd >/tmp/passwd.new
cat /tmp/passwd.new >/etc/passwd

Second, my dotfiles use zsh4humans, which installs itself — plugins, plus prebuilt fzf and gitstatusd binaries — the first time an interactive zsh starts. Doing that during the build instead buys two things: the shell works on a machine with no internet, and a download failure fails the build rather than the first login.

It costs about 67 MiB of files — 26 MiB of packages, 5 MiB of checkout, 28 MiB of z4h cache — which is 21 MiB of actual disk on the compressed btrfs default. 99-selftest checks it the way that matters: it starts an interactive zsh on the booted machine and confirms the repo’s .zshrc really was sourced.

Being the only hook that talks to GitHub also makes it the one most likely to fail a build. Set http_proxy and https_proxy when the path to GitHub is reliably bad rather than occasionally bad.

Weekly fstrim is installed regardless of ROOT_FS. Although a btrfs root already trims itself through discard=async, the job is not all about the root filesystem. A data disk attached to the instance later is quite likely to be ext4 or XFS, and nothing else in the image would ever trim it. For those, periodic trim is the currently recommended approach over -o discard.

The job also cannot be a one-liner, because a minimal Alpine image does not have util-linux:

1
2
3
4
5
6


fstrim -a 2>/dev/null && exit 0

awk '$1 ~ /^\/dev\// && !seen[$2]++ { print $2 }' /proc/mounts |
while IFS= read -r mp; do
 fstrim "$mp" 2>/dev/null
done

fstrim -a walks every mounted filesystem and de-duplicates devices, but that is util-linux’s fstrim. Busybox’s applet takes exactly one mount point and has no -a at all, so on the image as built the -a form fails and the loop does the work. My original fstrim -a || fstrim / looked like it handled that and did not: the fallback trimmed only the root, which is precisely the filesystem that needed it least.

Writing Your Own

Drop a script in hooks/, add its name to HOOKS. The whole hooks/ directory is copied into the chroot at /tmp/mkalpine, so a hook that needs to install a longer file can keep it in hooks/files/ and copy it from /tmp/mkalpine/files/ rather than embedding it in a heredoc:

1
2
3
4
5


#!/bin/sh
set -eu
apk add --quiet --no-progress my-thing
install -m 0644 /tmp/mkalpine/files/my-thing.conf /etc/my-thing.conf
rc-update add my-thing default

The number prefixes are a label, not a mechanism. This is not run-parts: nothing sorts the directory, and the run order is simply the order of the HOOKS list, so HOOKS="10-network my-thing 80-firstboot" does exactly what it looks like. Your hook can be called anything, go anywhere in the list, and it does not matter that the shipped extras have crowded the 90s — 99-selftest runs last because it is last in the list, not because of its number.

Two things about the environment a hook runs in. Everything in config.sh is exported into it, but nothing else is: the chroot starts from env -i, so a hook sees PATH, HOME, TERM, the config, and a proxy if one is configured. And it has no controlling terminal and /dev/null on stdin, for the reasons in 95-dotfiles above, so a hook cannot stop a build to ask a question — a program that tries gets EOF and fails, which is a build that ends with an error rather than one that waits all night.

Verifying The Image

An image that builds is not an image that boots, and an image that boots is not an image that is configured the way you asked. So there are two scripts.

Does It Boot

1
2


./testboot.sh -m uefi alpine.img
./testboot.sh -m bios alpine.img

This boots the image headless under QEMU with -snapshot, so the image is never modified, captures the serial console to a file, and waits for a login: prompt. Reaching the login prompt exercises the whole chain in one go: firmware → GRUB → kernel → initramfs → root mount → OpenRC → getty. On failure it prints the last 40 lines of the console, which is usually enough to see where it stopped. -w drops the -snapshot and lets the guest write to the image, for when you want to inspect what a first-boot service did to the disk.

It finds OVMF and AAVMF across the various paths different distributions use, and uses KVM when /dev/kvm is writable. With KVM, BIOS reaches the login prompt in about 16 seconds and UEFI in about 26 — OVMF initialization is the difference.

Is It Configured Correctly

Add the 99-selftest hook and pass -d:

1
2


HOOKS="$HOOKS 99-selftest" sudo ./mkalpine.sh -f alpine.img
./testboot.sh -d alpine.img

The hook installs a service that runs last in the default runlevel and checks the running system against the configuration it was built from. The expectations are baked in at build time, which is the part that makes it useful: a hook that silently did nothing shows up as a failure rather than as a plausible-looking dump.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


===== SELFTEST BEGIN =====
-- identity
 info machine-id=2767df9cefbfd2d2af2d0b8acdfb4aa5
 info hostkey=SHA256:U242JZNiEf+Qo3swIK+MoW4m2bdNb2eCMG5W6VJAwPM (ED25519)
 ok hostname is alpine
 ok machine-id is 32 hex digits
 ok timezone is UTC
-- filesystems
 info root options=rw,noatime,inode64,logbufs=8,logbsize=256k,noquota
 ok root is xfs
 ok /boot is vfat
 ok root mounted with logbsize=256k
 -- btrfs subvolume (not configured)
 ok fstab references root by UUID
-- boot
 info kernel=6.18.48-0-virt
 info cmdline=BOOT_IMAGE=/vmlinuz-virt root=UUID=e95aee24-... ro
 modules=sd-mod,usb-storage,xfs rootfstype=xfs
 rootflags=noatime,logbsize=256k console=tty0 console=ttyS0,115200
 ok cmdline is not quiet
 ok ttyS0 in securetty
-- hooks
 ok 20-ssh: PermitRootLogin is prohibit-password
 ok 20-ssh: listening on 22
 ok 40-zram: swap is ~100% of RAM
 ok 60-sysctl: congestion control is bbr
 ok 70-growroot: removed itself from the default runlevel
 ok 70-growroot: root fs fills the partition
 ok 80-firstboot: host key is not the build host's
 -- 91-ufw (disabled)
-- hygiene
 ok apk cache is empty
 ok no build scratch left behind
 ok repositories pinned to v3.24
 ok repositories do not track latest-stable
-- sizing
 Filesystem Size Used Available Use% Mounted on
 /dev/vda3 381.0M 161.2M 219.8M 42% /
 /dev/vda2 63.0M 36.4M 26.6M 58% /boot
SELFTEST RESULT: 59 passed, 0 failed
===== SELFTEST END =====

(abridged; the real report is one line per check)

testboot.sh -d exits non-zero if any check failed, so it works in a loop.

The checks live in hooks/files/selftest.initd as an ordinary shell script rather than a heredoc, and check takes a command with its arguments instead of a string to eval:

1
2
3
4


check "root is $EXPECT_ROOT_FS" fstype_is / "$EXPECT_ROOT_FS"
check "machine-id is populated" test -s /etc/machine-id
check "cmdline is not quiet" not grep -qw quiet /proc/cmdline
check "60-sysctl: vm.swappiness is 180" output_is 180 sysctl -n vm.swappiness

Anything needing a pipeline gets a named predicate instead. The first version of this used eval on quoted strings and was unreadable — check "root is btrfs" "awk '\$2 == \"/\" {print \$3}' /proc/mounts | grep -qx btrfs" — which is a good sign that the abstraction was wrong.

Everything At Once

1

sudo ./testmatrix.sh -o /var/tmp/mx

This builds btrfs/ext4/xfs × gpt/mbr, boot-tests all six under both BIOS and UEFI with the selftest enabled, then checks the things that only show up at runtime:

Growth. Copy an image, truncate -s 4G, and boot it — with testboot.sh -w, so the guest’s writes actually land in the file instead of in QEMU’s -snapshot overlay. Then confirm the root partition grew (911,360 → 8,253,407 sectors) and that it still starts on its original sector, because a growpart that moved the start would silently discard the build-time alignment. Reading the table back from the un-booted copy would have made this test tautological, which is what it was until I looked closely.
Output formats. Build with all five, confirm each file exists, and boot the qcow2 directly rather than just checking that qemu-img produced something.
Identity. Boot the same image twice and confirm the two boots produce different SSH host key fingerprints and machine-ids.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


== build and boot matrix ==
ok build btrfs/gpt
ok boot btrfs/gpt/uefi
ok boot btrfs/gpt/bios
...
== growroot on a larger disk ==
ok grow 4G
ok grow root partition 1959936 -> 8253407 sectors, still at 135168
== output formats ==
ok format formats.img.zst (74M)
ok boot qcow2
== identity is per-boot, not per-image ==
ok hygiene two boots produced different SSH host keys
ok hygiene two boots produced different machine-ids
== summary ==
29 passed, 0 failed

Four real bugs in this post were found this way. The XFS logbsize downgrade above was one, and the tautological growth check was another. The third was in the selftest itself: I had written

1

check "apk cache is empty" not ls -A /var/cache/apk

which reads correctly and means the opposite, because ls -A exits 0 on an empty directory. A test suite that catches bugs in its own checks is doing its job.

The last one showed up when I dropped the default IMAGE_SIZE from 1 GiB to 512 MiB. All three filesystems still built and booted, but ext4 and XFS started failing 70-growroot: root fs fills the partition, which had been written as “df size is at least 90% of the partition”. Nothing was wrong with the images: df excludes reserved blocks and fixed metadata, and on a 445 MiB root partition that fixed cost is 44 MiB for ext4 and 64 MiB for XFS — 90.0% and 85.6%. The same filesystems on a 957 MiB partition reported 96.5% and 93.3% and passed. A percentage was simply the wrong shape for the check, because the overhead it has to tolerate barely moves with the disk size while the threshold does. The failure it exists to catch is not marginal either — a root that never grew is a 445 MiB filesystem in a 4 GiB partition — so the tolerance is now the larger of 96 MiB and 10%.

Uploading

Most providers want a compressed raw image or a qcow2:

1

sudo OUTPUT_FORMATS="raw.zst" ./mkalpine.sh -f alpine.img

If your provider has no image import at all — which is the common case on the cheap tiers — the restore-over-dd trick from the old post still applies: boot their stock OS, dd the image onto the disk from a rescue environment or over SSH, and reboot. 70-growroot then handles the fact that their disk is larger than the image.

That flow needs a console or a rescue system at one point or another. When the provider offers neither — no VNC, no serial, no rescue mode, just the stock OS and SSH, which is what the smallest NAT’d tiers look like — use the no-console variant in the old post instead: reinstall dd mode arranges a RAM-resident Alpine by rewriting the stock bootloader, then writes the image over the whole disk and reboots, all over SSH. It accepts the raw.gz / raw.zst / raw.xz artifacts from OUTPUT_FORMATS as-is, and it does not modify a Linux image — which, on a headless box, promotes 10-network and 20-ssh from conveniences to the difference between a machine that comes back and a reinstall ticket.

What I Kept From The Old Post

Everything about why. The old post explains the 64 MiB /boot, the compressed Btrfs root, the absence of disk swap, and the individual tweaks in far more detail than a config file comment can, and it is still the reference for doing this by hand on a machine you have already booted. This post is the automation of it.

Minimal Alpine Linux on a 1 GB Btrfs Root Disk

Thu, 25 Jun 2026 15:00:00 +0800

I sometimes need a tiny cloud instance that only forwards traffic. CPU and memory can be small, and the disk is mostly wasted space. On one Alibaba Cloud ecs.t6-c4m1.large instance, a 1 GB root disk on a long contract can push the cost down to about $0.40/month, but a normal Linux install leaves too little usable space.

The trick is not complicated:

Use Alpine Linux, because the base system is small.
Keep /boot tiny. A 512 MB boot partition is absurd on a 1 GB disk.
Put / on Btrfs with transparent compression. Application files, package metadata, and logs usually compress well.
Do not allocate disk swap. Use zram later if the machine needs swap-like behavior.

This post is the install recipe I use to build a minimal BIOS/MBR Alpine image, then optionally convert it to QCOW2 for reuse.

If you would rather not do this by hand, I later automated the whole thing: Building Alpine Linux Disk Images Without a VM is a script that builds the same class of image as a file, with no VM and no interactive steps, and boots under both BIOS and UEFI. This post is still the explanation of why the pieces are the way they are.

Assumptions

This guide targets a very specific VM shape:

Legacy BIOS boot with MBR and Syslinux/Extlinux.
One small ext4 /boot partition and one Btrfs root partition.
No disk encryption, no LVM, no UEFI, no separate /var.
The whole disk can be destroyed.

If your VM boots with UEFI, use an EFI system partition and GRUB instead. If your disk is NVMe, adapt the partition names to /dev/nvme0n1p1 and /dev/nvme0n1p2.

The final layout is:

Partition	Size	Filesystem	Mountpoint
`/dev/vda1`	64 MB	ext4	`/boot`
`/dev/vda2`	Rest of disk (~500MB is fine)	Btrfs	`/`

64 MB is enough for this single-kernel Alpine image. The boot partition usage should be around 30M with Alpine 3.23 virt kernel (6.18). If you plan to keep multiple kernels or use a larger bootloader setup, use 128 MB instead.

Before you start installing, create a VM with a ~512MB disk (yes, really). CPU and RAM can be small, because the install process is not resource-intensive. After the install, you can resize the disk to 1 GB or larger.

Always go with a small disk first because the disk image can be expanded easily, but shrinking a disk is not trivial.

Partition The Disk

Set the disk variables so the commands below are harder to mistype:

1
2
3


DISK=/dev/vda
BOOT=/dev/vda1
ROOT=/dev/vda2

Now create a DOS/MBR partition table with a tiny boot partition:

1

fdisk "$DISK"

Inside fdisk, enter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


o # new empty DOS partition table
n # new partition
p # primary
1 # partition number
2048 # first sector, 1 MiB aligned
+64M # size
a # toggle bootable flag
1

n # new partition
p # primary
2 # partition number
133120 # first sector immediately after the 64 MB partition
 # press Enter for the default end sector

p # verify the table
w # write changes

The important details are:

/dev/vda1 should be bootable.
/dev/vda1 should start at sector 2048.
/dev/vda2 should start at sector 133120.
The second partition should use the rest of the disk.

Check that the kernel sees the new partitions:

1

ls -l /dev/vda*

If /dev/vda1 and /dev/vda2 do not appear, reboot the live ISO. Alpine’s manual disk setup docs also recommend rebooting after manual partition creation when needed.¹

Start Alpine Setup

Download the latest Alpine ISO from https://alpinelinux.org/downloads/. I usually use the x86_64 architecture and the virtual variant. As this will be used in virtualized environments, the virt kernel is smaller.

Boot the Alpine ISO and log in as root. The live environment has no root password by default.

Run the normal installer first:²

1

setup-alpine

Answer the usual questions for keyboard, hostname, network, DNS, root password, timezone, mirror, SSH, and NTP. I usually choose chrony for NTP.

When it asks which disk to use, type:

1

none

This keeps the base configuration but skips automatic partitioning and formatting. For the later diskless-mode prompts, also choose none for configs. You can keep the default apk cache dir (/var/cache/apk).

Format And Mount

Install the filesystem tools in the live environment:

1

apk add btrfs-progs e2fsprogs

Format /boot as ext4 and / as Btrfs:

1
2


mkfs.ext4 -m 0 -L boot "$BOOT"
mkfs.btrfs -f -L alpine-root "$ROOT"

Mount root with compression enabled:

1
2
3
4
5
6


# adjust the compression level as desired. zstd:1 is fast and has reasonable compression. zstd:3 is slower but compresses better. Any higher level is usually overkill and comes with diminishing returns.
mount -t btrfs -o rw,relatime,compress=zstd:3,ssd,discard=async,space_cache=v2 "$ROOT" /mnt
btrfs property set /mnt compression zstd:3

mkdir -p /mnt/boot
mount -t ext4 "$BOOT" /mnt/boot

I keep /boot on ext4 because it is small and predictable with this Syslinux/MBR setup. On a tiny image, boring boot is good boot.

Install Alpine

Install Alpine into the mounted filesystem:

1

setup-disk -v -m sys -s 0 /mnt

The options mean:

-m sys: install a traditional persistent system to disk.
-s 0: do not create disk swap.
/mnt: use the partitions already mounted under /mnt.

This is the standard setup-disk -m sys /mnt flow, just with a manually prepared root filesystem.³

Verify fstab And initramfs

Check /mnt/etc/fstab before rebooting:

1

vi /mnt/etc/fstab

The root entry should include Btrfs compression. Mine looks like this:

1
2


UUID=... / btrfs rw,relatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=5,subvol=/ 0 1
UUID=... /boot ext4 rw,relatime 0 2

Remove any stale cdrom or usbdisk entries if the installer generated them.

Also check that the installed initramfs knows about Btrfs:

1

grep -w btrfs /mnt/etc/mkinitfs/mkinitfs.conf

If btrfs is missing from features="...", add it before rebooting and regenerate the initramfs from a chroot. Alpine explicitly calls this out for manual Btrfs root installs.⁴

Fix The MBR Bootloader

On these tiny MBR images, I have seen the first-stage bootloader not get written correctly. Reinstalling the Syslinux MBR is cheap insurance:

1
2


apk add syslinux
dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of="$DISK"

Use gptmbr.bin instead only if you are using GPT. For the DOS partition table above, mbr.bin is the right file.⁵

Now unmount and reboot:

1
2
3
4
5


cd /
sync
umount /mnt/boot
umount /mnt
reboot

After the first boot, log in and check the actual space usage:

1
2


df -h /
btrfs filesystem usage /

Convert The Disk To QCOW2

Once the image is configured the way you want, shut it down and convert the raw disk from the host:

1

qemu-img convert -f raw -c -p -O qcow2 /dev/mapper/ex950-vm--300--disk--0 alpine-minimal.qcow2

Replace the source device with your VM disk. Do this from a stopped VM or a consistent snapshot, not from a running writable system.

You can now reuse the QCOW2 as a base image for other VMs or cloud instances.

Restore From The Provider’s Original OS

Some cloud providers do not let you upload or boot a custom disk image. If you still have VNC/serial-console access, another way is to boot the provider’s original Linux image, download your Alpine QCOW2 there, convert it to raw, then reboot into the original OS initramfs and overwrite the whole disk from there.

The important reason for the two-stage flow is tooling: the original OS probably has curl and qemu-img, while the initramfs usually does not. The initramfs is only used for the final dd, because at that point the real root filesystem is not mounted and can be safely overwritten.

This is destructive. Double-check the target disk and the old root partition before running dd.

First, in the provider’s original OS. This filesystem needs enough free space to hold both the downloaded QCOW2 and the converted raw image:

1
2
3
4
5


# Download the Alpine minimal image in qcow2 format and convert it to raw.
# Do this in the original OS because the initramfs probably does not have
# curl or qemu-img.
curl -L "<qcow2 link>" -o /os.qcow2
qemu-img convert -f qcow2 -O raw /os.qcow2 /os.raw

Then use the provider console or VNC to reboot into initramfs. On a GRUB-based original OS, select the normal boot entry, press e, find the Linux kernel command line, append:

1

break=premount

Then press F10 or Ctrl-x to boot. This should drop you into an initramfs shell before the root filesystem is mounted.

From the initramfs shell:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# Find the old root partition and the target disk.
# Example:
# old root partition: /dev/sda2
# target disk: /dev/sda
cat /proc/partitions

mkdir /tmp/rootfs
cd /tmp

# Mount the old root filesystem read-only to copy the prepared image.
# Replace /dev/sda2 with the root partition from the original OS, and
# replace ext4 if the provider image uses another filesystem.
mount -t ext4 -o ro /dev/sda2 rootfs

# Copy the raw image to initramfs memory so the old root can be unmounted
# before overwriting the disk.
#
# This requires enough RAM for /os.raw. If the VM is too small, attach a
# temporary rescue disk or use a rescue system that can stream the image
# from the network instead.
dd if=rootfs/os.raw of=os.raw

umount rootfs

# This overwrites the whole disk. Replace /dev/sda with the target disk.
dd if=os.raw of=/dev/sda

reboot

After booting into Alpine, apply provider-specific network settings. For a static IPv4 setup:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


cat <<'EOF' > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
 address X.X.X.X/24
 gateway X.X.X.X
EOF

cat <<'EOF' > /etc/resolv.conf
nameserver 1.1.1.1
nameserver 1.0.0.1
EOF

setup-hostname XXXX

rc-service networking restart

If the provider uses DHCP, keep the interface as DHCP instead and let Alpine request the address normally.

Restore Without A Console Or Rescue Mode

The cheapest tiers take the rest of it away too: no custom-image import, no VNC, no serial console, no rescue mode. The stock OS and SSH are all you get. The initramfs trick above is unreachable there, because its one console step — interrupting GRUB — has no SSH equivalent: an initramfs shell has no network stack and no sshd.

What still works is having a script arrange that environment for you. bin456789/reinstall rewrites the stock bootloader to boot a minimal Alpine that runs entirely in RAM, and from there downloads your image and dds it over the whole disk before rebooting into it. No console is involved at any point. You watch the progress over SSH, and if the download or the write fails, the RAM system keeps its sshd up, so a failure is a retry by hand rather than a reinstall ticket.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# From the provider's stock OS, as root. This is destructive: it will
# wipe the whole disk, other partitions included.
#
# Mainland-China boxes often cannot reach raw.githubusercontent.com; the
# project mirrors the script at cnb.cool for exactly that case.
curl -O https://raw.githubusercontent.com/bin456789/reinstall/main/reinstall.sh
# curl -O https://cnb.cool/bin456789/reinstall/-/git/raw/main/reinstall.sh

# Prompts for a username/password, used to log in over SSH and watch.
# .gz / .xz / .zst compressed raw images are accepted directly.
bash reinstall.sh dd --img="https://example.com/alpine.img.gz"

# Still reversible until here: `bash reinstall.sh reset` restores the
# original bootloader config.
reboot

Before it does anything, the script asks for a username and a password, and it is worth being clear about what they are not: the new system’s login. They exist only inside the RAM installer environment — they are what you would type to SSH back in while the dd runs, to watch progress or clean up after a failure. A Linux image gets nothing injected; the script’s own end-of-run summary says as much, printing Password: [Depends on image] under “After Install”. So press Enter twice — root, then a random password the summary displays for copying — and let whatever the image baked in be the machine’s real credentials. --ssh-key replaces that password with one of your public keys for the installer environment, if typing nothing at all is the goal.

When you do log in mid-install, expect a host-key mismatch: the RAM environment presents its own host keys, and so does the finished image, so the client will complain about the stock OS’s key on the way in and about both of them after the final reboot. That is the process working, not something broken — clear the old entry with ssh-keygen -R or accept the new key each time. On a NAT’d box the installer’s sshd still listens on port 22 internally, so the provider’s forwarded port keeps working throughout.

Four things to get right, all of them consequences of there being no console:

The image URL must be reachable from the VPS. The download runs inside the RAM environment, over the same network the stock OS uses. For a box in mainland China that usually rules out GitHub-hosted files; one of my own servers or local object storage works better.

The image has to work as-is. dd mode does not modify a Linux image, so the network settings, the SSH keys, and the sshd port must be baked into the image before flashing — the “apply provider-specific network settings” step above has to happen inside the image, not on the machine afterwards. On a NAT’d box, where the provider forwards one public port to (say) internal port 22, changing the sshd port in the image orphans that forward and the machine. If the image comes from the builder, the 10-network and 20-ssh hooks are where this goes.

Check whether the stock OS keeps its root on LVM before rebooting. The script stages reinstall-vmlinuz and reinstall-initrd in the stock OS’s root directory and lets GRUB find them with search --file. GRUB’s LVM support is incomplete — thin-provisioned volumes are unsupported outright, and some perfectly ordinary LVM roots also defeat it for reasons that are not understood (issue #355). When that happens, GRUB stops at file '/reinstall-vmlinuz' not found and the RAM environment is never reached. On a machine with a console that is a visible error; on this kind of machine the box reboots and simply never speaks again. One lsblk settles it beforehand — if / sits on an lvm device, copy both files to /boot, which Debian-style LVM installs keep on a plain partition that GRUB reads reliably:

1
2


lsblk -o NAME,TYPE,FSTYPE,MOUNTPOINTS # is / on an lvm device?
cp /reinstall-vmlinuz /reinstall-initrd /boot/

The copies are harmless if they were not needed: search --file scans every filesystem GRUB can read, so it finds the /boot copies whenever the LVM ones are invisible. The workaround is the tool author’s own, from the issue thread. If /boot is only a directory inside the LVM root, there is no plain partition to stage onto, and I would not run this flow on such a box without a console.

Audit before the final reboot. --hold 2 stops after the dd finishes but before the reboot. SSH back in, mount the freshly written root and boot partitions read-write, and check /etc/network/interfaces, the authorized keys, and the bootloader config while a mistake is still fixable with a text editor. It is the last moment anything is.

The RAM environment is small — the project lists 256 MB of RAM as the minimum — so this works on boxes too tiny for anything else. To drive the final dd by hand instead, bash reinstall.sh alpine --hold 1 boots the same RAM Alpine and stops there, nothing written; it is also a cheap dry run for whether that environment’s networking works on the provider’s NAT at all. And if the machine still does not come back after the last reboot, the floor is the provider’s own reinstall button, back to the stock OS — annoying, not fatal.

Things I Bake Into The Image

The base install above is intentionally small. The sections below are optional knobs I usually apply before making the reusable image.

SSH

For a private forwarding box, I allow root SSH and TCP forwarding. Use key auth and firewall rules if this machine is reachable from the public Internet.

Add or change these lines in /etc/ssh/sshd_config:

1
2
3
4


PermitRootLogin yes
AllowTcpForwarding yes
ClientAliveInterval 60
ClientAliveCountMax 3

Restart SSH:

1

rc-service sshd restart

ClientAliveInterval 60 plus ClientAliveCountMax 3 makes dead SSH forwarding sessions disappear after roughly three minutes instead of waiting for long TCP timeouts.

Community Repository

Many useful packages live in community.

Either run:

1

setup-apkrepos -c

Or edit /etc/apk/repositories and uncomment the matching community repository:

1

# http://dl-cdn.alpinelinux.org/alpine/<alpine version>/community

Then refresh indexes:

1

apk update

IPv6 DHCP

SLAAC may work without any configuration. Some cloud providers need DHCPv6, in which case add an IPv6 stanza to /etc/network/interfaces:

1
2
3


auto eth0
iface eth0 inet dhcp
iface eth0 inet6 dhcp

Install the DHCP and interface tooling if your image does not already have it:

1
2


apk add dhcpcd ifupdown-ng
rc-service networking restart

Chrony

If NTP was not configured during install:

1
2
3
4
5
6
7
8
9


apk add chrony
vi /etc/chrony/chrony.conf

# Use `ntp.aliyun.com` if you are in mainland China; `pool.ntp.org`
# is often unreliable from there. Elsewhere, the default pool is fine.
#
# Also add `makestep 1.0 -1` so chrony can correct large time offsets
# on startup, which is common in VMs. You can remove the default
# `initstepslew ...` line if it exists.

The result should look like this:

1
2
3
4
5
6


pool pool.ntp.org iburst
initstepslew 10 pool.ntp.org
driftfile /var/lib/chrony/chrony.drift
rtcsync
cmdport 0
makestep 1.0 -1

Enable it:

1
2


rc-update add chronyd default
rc-service chronyd restart

Log Caps

Alpine does not install a full log rotation stack by default. On a 1 GB disk, I prefer a tiny periodic script that keeps one backup and truncates logs in place so daemons can continue writing.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


cat <<'EOF' > /etc/periodic/hourly/logtruncate
#!/bin/sh

# Rotate log files larger than 4M.
# Keep one .0 backup and truncate the original in place.

LOG_DIR="/var/log"
MAX_SIZE=$((4 * 1024 * 1024)) # 4M in bytes

find "$LOG_DIR" -type f ! -name '*.0' | while read -r file; do
 # Works with both GNU and BusyBox stat.
 size=$(stat -c %s "$file" 2>/dev/null || stat -f %z "$file" 2>/dev/null || echo 0)

 if [ "$size" -gt "$MAX_SIZE" ]; then
 logger -t logtruncate "Rotating $file ($size bytes)"

 # Copy current content to .0 backup, overwriting the old backup.
 cp "$file" "$file.0"

 # Preserve the inode so daemons can continue writing.
 truncate -s 0 "$file"

 logger -t logtruncate "Rotated $file (backup: $file.0)"
 fi
done
EOF

chmod +x /etc/periodic/hourly/logtruncate
rc-update add crond default
rc-service crond start

Then tell BusyBox syslog not to rotate by itself:

1
2


sed -i 's/^SYSLOGD_OPTS=.*/SYSLOGD_OPTS="-t -s 0"/' /etc/conf.d/syslog
rc-service syslog restart

APK Cache Cleanup

If apk caching is enabled later, clean old packages periodically:

1
2
3
4
5
6
7


cat <<'EOF' > /etc/periodic/daily/apkcacheclean
#!/bin/sh
find /var/cache/apk -type f -name '*.apk' -mtime +7 -delete
find /var/cache/apk -type f -name '*.tar.gz' -mtime +90 -delete
EOF

chmod +x /etc/periodic/daily/apkcacheclean

Timezone

1
2


apk add tzdata
setup-timezone -z Asia/Shanghai # replace with your timezone

ZeroTier

Alpine’s ZeroTier package can lag behind upstream, so I usually use static binaries from zerotier-static.

After placing zerotier-one at /usr/local/bin/zerotier-one, create an OpenRC service:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


cat <<'EOF' > /etc/init.d/zerotier-one
#!/sbin/openrc-run

depend() {
 after network-online
 want cgroups
}

start_pre() {
 /sbin/modprobe tun
}

supervisor=supervise-daemon
name=zerotier-one
command="/usr/local/bin/zerotier-one"
command_args=" \
 >>/var/log/zerotier-one.log 2>&1"

output_log=/var/log/zerotier-one.log
error_log=/var/log/zerotier-one.log

pidfile="/var/run/zerotier-one.pid"
respawn_delay=5
respawn_max=0
EOF

chmod +x /etc/init.d/zerotier-one
rc-update add zerotier-one default
rc-service zerotier-one start

ZRAM Swap

Zram is more useful than disk swap. Install zram-init:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


apk add zram-init

# Adjust as needed. The default config creates swap and /tmp on zram.
#
# I usually set swap zram to roughly the same size as RAM and use lz4
# for speed. Because zram compresses memory, that does not mean it
# immediately consumes that much physical RAM.
#
# To set swap zram to the same size as RAM, remove the default
# `size0=512M` line and use:
# size0=`LC_ALL=C free -m | awk '/^Mem:/{print int($2)}'`
#
# To use lz4:
# algo0=lz4
#
# The /tmp zram can be left untouched. If you want a smaller /tmp, use
# something like:
# size1=`LC_ALL=C free -m | awk '/^Mem:/{print int($2/4)}'`
#
# Remove `blck1=1024` if your default config has it. The minimum block
# size is 4 KiB, so 1024 bytes is not valid.
#
# If /tmp is already mounted as tmpfs in /etc/fstab, remove that line
# when /tmp is provided by zram-init.
vi /etc/conf.d/zram-init

rc-update add zram-init boot
rc-service zram-init start

These sysctls make the kernel more willing to use compressed swap:

1
2
3
4
5
6
7
8


cat <<'EOF' > /etc/sysctl.d/01-zram.conf
vm.swappiness = 180
vm.watermark_boost_factor = 0
vm.watermark_scale_factor = 125
vm.page-cluster = 0
EOF

sysctl -p /etc/sysctl.d/01-zram.conf

Cloud-init

cloud-init is convenient if the image will be imported into a cloud provider, but it pulls in Python and is not small.

1
2
3


apk add cloud-init
# Read the installation notes displayed by apk. It will show which
# cloud-init services should be enabled for your target environment.

Read the package message after installation and enable the OpenRC services it lists. If you want automatic partition growth on first boot, also install:

1

apk add cloud-utils-growpart

For the smallest image, skip cloud-init and inject network configuration another way.

Expand Root After Restoring To A Larger Disk

If you restore the QCOW2 to a larger disk, grow the root partition and then grow Btrfs.

Run:

1

fdisk /dev/vda

Inside fdisk:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


p # print; write down the current start sector of vda2, usually 133120
d # delete partition
2 # select vda2

n # new partition
p # primary
2 # partition number 2
133120 # use the exact old start sector
<ENTER> # default end, use the rest of the disk

> If asked:
> Partition #2 contains a btrfs signature.
> Do you want to remove the signature? [Y]es/[N]o:

N # DO NOT remove the signature

p # verify vda2 starts at the same sector and uses the rest of the disk
w # write changes

Ask the kernel to reread the partition table:

1
2


apk add parted
partprobe /dev/vda || reboot

If you had to reboot, continue after the reboot:

1
2


btrfs filesystem resize max /
df -h /

I prefer this manual method over blindly using a grow tool because it actually expands and aligns, while some grow tools may not expand the partition to be 4K aligned.

BBR Congestion Control

For forwarding boxes, I usually enable BBR:

1
2
3
4
5
6


cat <<'EOF' > /etc/sysctl.d/02-bbr.conf
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr
EOF

sysctl -p /etc/sysctl.d/02-bbr.conf

Verify:

1

sysctl net.ipv4.tcp_congestion_control

Podman

If I need containers on a tiny VM, I prefer Podman over Docker because the entire stack (no containerd, crun instrad of runc, lighter daemon).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


apk add podman

# Keep the overlay storage driver. It is usually more stable and has
# better performance for containers, even though the underlying
# filesystem is Btrfs.
#
# Limit container logs to 1M so they do not fill the disk.
sed -i 's/^#log_size_max =.*/log_size_max = 1048576/' /etc/containers/containers.conf

# Enable cgroups v2 for better compatibility with modern container runtimes.
rc-update add cgroups default
rc-service cgroups start

# Start containers that have a restart policy such as always or unless-stopped.
rc-update add podman default
rc-service podman start

If you want Docker CLI and Compose compatibility against the Podman socket:

1
2
3
4


apk add docker-cli docker-cli-compose

docker context create podman --docker "host=unix:///run/podman/podman.sock"
docker context use podman

I do not use podman-docker or podman-compose here; the Docker CLI is closer to what my existing Compose files expect.

UFW

If the provider does not give you a firewall, configure one before exposing the VM:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73


apk add ip6tables ufw
# Start ufw later, after the allow rules are in place.

# Default policies
ufw default deny incoming
ufw default allow outgoing

# Allow loopback
ufw allow in on lo

# -------------------------
# SSH
# -------------------------

# SSH port; change this if you use a non-standard SSH port.
ufw allow 22/tcp comment 'SSH'

# Optional: rate limit SSH brute force.
# ufw limit 22/tcp

# -------------------------
# Private / intranet ranges
# -------------------------

# RFC1918 IPv4
ufw allow from 10.0.0.0/8
ufw allow from 172.16.0.0/12
ufw allow from 192.168.0.0/16

# Optional CGNAT range
# ufw allow from 100.64.0.0/10

# Optional IPv6 ULA
ufw allow from fc00::/7

# Also allow forwarding to RFC1918 and ULA ranges if this server is a
# gateway or VPN server, or if you use Podman containers with published
# ports. Published container ports usually pass through DNAT and are
# handled by forward rules.
#
# Note that if you are using Podman containers with published ports,
# these route rules can allow access to all published ports even if the
# input rules only allow selected ports. If that is not what you want,
# only allow specific forwarded ports here.
# ufw route allow to 10.0.0.0/8
# ufw route allow to 172.16.0.0/12
# ufw route allow to 192.168.0.0/16
# ufw route allow to fc00::/7

# -------------------------
# Public services
# -------------------------

# Web
# ufw allow 80/tcp
# ufw allow 443/tcp
# ufw allow 443/udp

# Example app ports
# ufw allow 3000/tcp
# ufw allow 9090/tcp

# -------------------------
# Logging
# -------------------------

ufw logging low

# Enable firewall
ufw enable

rc-update add ufw default
rc-service ufw start

If this machine routes VPN, overlay network, or container traffic, add explicit ufw route allow ... rules for the private ranges you actually need.

sshguard

I avoid Fail2ban on this image because Python is too heavy for the target machine. sshguard is small and good enough.

1

apk add sshguard nftables

Do not blindly start the nftables service before checking its default ruleset from a console. On one of my Alpine images, doing that installed a default deny ruleset and locked out remote SSH. I let sshguard manage its own nftables sets instead.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


# IMPORTANT: Do not run `rc-update add nftables && rc-service nftables start`
# unless you have checked the ruleset from a console. We will let sshguard
# manage its nftables sets.

mkdir -p /var/lib/sshguard

cat <<'EOF' > /etc/sshguard.conf
# Full path to backend executable. Required; there is no default.
BACKEND='/usr/libexec/sshg-fw-nft-sets'

# Space-separated list of log files to monitor.
FILES='/var/log/messages'

# Block attackers when their cumulative attack score exceeds THRESHOLD.
# Most attacks have a score of 10.
THRESHOLD=20

# Block attackers for initially BLOCK_TIME seconds after exceeding THRESHOLD.
# Subsequent blocks increase by a factor of 1.5.
BLOCK_TIME=180

# Remember potential attackers for up to DETECTION_TIME seconds before
# resetting their score.
DETECTION_TIME=3600

# Permanently blacklist attackers when their cumulative score exceeds threshold.
BLACKLIST_FILE=100:/var/lib/sshguard/blacklist.db

# Size of IPv6 subnet to block. Defaults to a single address.
IPV6_SUBNET=48

# Size of IPv4 subnet to block. Defaults to a single address.
IPV4_SUBNET=24
EOF

rc-update add sshguard default
rc-service sshguard start

Common Tools

This is no longer minimal, but it makes Alpine feel closer to a general-purpose server if you find busybox too limited:

1
2


apk add bash coreutils findutils tar grep sed gawk diffutils procps util-linux shadow curl wget iproute2 bind-tools gcompat pciutils
apk add netcat-openbsd socat tcpdump iftop iptraf-ng ethtool traceroute zsh git htop tmux vim less jq iperf3 sysstat rsync file

And other tools

1

apk add bat dufs gdu lsd yazi

Final Notes

The most important part of this setup is the partitioning discipline. On a 1 GB disk, a lazy 512 MB /boot, a swap partition, or unbounded logs will consume the entire machine faster than the application does.

With a 64 MB /boot, compressed Btrfs root, no disk swap, and a few periodic cleanup jobs, Alpine stays usable even on tiny cloud disks. It is not luxurious, but it is enough for a forwarding node or a small single-purpose service.