alpinelinux / alpine-make-vm-image

Make customized Alpine Linux disk image for virtual machines

Make Alpine Linux VM Image

This project provides a script for making customized Alpine Linux disk images for x86_64 and aarch64 ^[1] virtual machines. You can choose between BIOS mode (using Syslinux, only for x86_64) and UEFI mode (using Linux EFI stub). It’s quite simple (400 LoC of shell), fast (~32 seconds on GitHub Actions), requires minimum dependencies (QEMU and filesystem tools).

Tip	Don’t need VM, just wanna chroot into Alpine Linux? Try alpine-chroot-install! Or do you want to create a custom rootfs? Then alpine-make-rootfs is for you!

Requirements

• Linux system with common userland (Busybox or GNU coreutils)

• POSIX-sh compatible shell (e.g. Busybox ash, dash, Bash, ZSH)

• qemu-img and qemu-nbd tools

• rsync (needed only for --fs-skel-dir)

• sfdisk (needed only for --partition, --boot-mode UEFI and non-x86 architectures)

• mdev or udevadm (needed only for --partition, --boot-mode UEFI and non-x86 architectures if device hotplug doesn’t work)

• e2fsprogs (for ext4), btrfs-progs (for Btrfs), or xfsprogs (for XFS)

• dosfstools (needed only for --boot-mode UEFI and non-x86 architectures)

All dependencies except the first two are automatically installed by the script when running on Alpine Linux.

Usage

Read documentation in alpine-make-vm-image. See .github/workflows/ci.yml for GitHub Actions example.

You can copy alpine-make-vm-image into your repository or download it on demand, e.g.:

wget https://raw.githubusercontent.com/alpinelinux/alpine-make-vm-image/v0.13.0/alpine-make-vm-image \
    && echo '0fe2deca927bc91eb8ab32584574eee72a23d033  alpine-make-vm-image' | sha1sum -c \
    || exit 1

Or, if you are on Alpine Linux, you can simply install the alpine-make-vm-image package.

Howtos

Create images for aarch64 on x86_64 host

All you need to do is install the QEMU User space emulator for aarch64 and register it in binfmt_misc as the interpreter for aarch64 binaries.

On Alpine Linux

apk add qemu-aarch64 qemu-openrc
rc-service qemu-binfmt start

On Debian/Ubuntu

apt-get install -y --no-install-recommends binfmt-support qemu-user-static
update-binfmts --enable

On Fedora

dnf install qemu-user-static

On GitHub Actions

- name: Install qemu-aarch64 and register in binfmt
  uses: jirutka/setup-alpine@v1
  with:
    arch: aarch64

See .github/workflows/ci.yml for a complete example.

After that, run alpine-make-vm-image with the option --arch aarch64.

Create aarch64 image with Alpine v3.18 or older

The Linux kernel (linux-virt, linux-lts or linux-edge package) in Alpine v3.18 and earlier doesn’t have EFI_ZBOOT enabled, so EFI stub cannot load a compressed vmlinuz. We backported it to v3.18, but then we had to revert it due to a problem with Grub (see alpine/aports#15263).

If you want to build an image with an older branch of Alpine Linux, you can, but you must install the kernel from the v3.19 branch (or newer). This is relatively safe because the kernel package doesn’t have any dynamic dependencies.

1. Create a repositories file with a pinned main repository from v3.19, e.g.:

   @v319 https://dl-cdn.alpinelinux.org/alpine/v3.19/main
   https://dl-cdn.alpinelinux.org/alpine/v3.18/main
   https://dl-cdn.alpinelinux.org/alpine/v3.18/community

2. Run alpine-make-vm-image with the options --repositories-file ./repositories and --packages linux-virt@v319 (or linux-lts@v319 if you use --kernel-flavor lts).

This will first install linux-virt from v3.18, but in the later step it will reinstall it from the v3.19 branch.

Create image for VMware (ESXi)

VMware and disk images (virtual disks) is one big mess. You can find that VMware uses the VMDK format, but the problem is that this is not a single format. Actually it has many subformats with very different structure and various (in)compatibility with VMware hypervisors.

When I’ve created a disk image using qemu-img create -f vmdk or converted Qcow2 to VMDK using qemu-img convert -O vmdk, vSphere client loaded this image without any problem, but the data was corrupted. Eventually I found in some old documentation that ESXi does not support “sparse” disks…

So after many trials I found out that the least bad and functional solution is to create Qcow2 image and then convert it to VMDK using:

qemu-img convert -f qcow2 -O vmdk -o adapter_type=lsilogic,subformat=monolithicFlat alpine.qcow2 alpine.vmdk

Unfortunately, this creates a “thick” image, i.e. its size equals the “provisioned space”, not actually used space as in Qcow2. However, you can compress it with gzip to avoid transferring multiple gigabytes of zeros over network.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.

---

1. Supported since Alpine Linux v3.19. See Create aarch64 image with Alpine v3.18 or older.

alpine-make-vm-image's Issues

Automate Alpine Linux installation

I am trying to achieve unattended Alpine Linux installation. I went through the Alpine automatic installation guide but when I follow this guide there are many manual interventions are needed during the installation! one during writing the root user name, another time when creating the answer file (setup-alpine -c answerfileName), editing the answer file, calling the actual installation command (setup-alpine -f answerfileName) and reset the root password. Is there any way to include the answer file inside the ISO image and select the root user by default before starting the installation and set its password as well after the installation is done (something similar to the kickstart file in the Centos distro) ?

Like in CentOS we can provide kickstart file like below in isolinux.cfg

label MyMENU2
  menu label ^Deploy Manager Node
  kernel vmlinuz
  append initrd=initrd.img inst.stage2=hd:LABEL=MYISO inst.ks=hd:LABEL=MYISO:/ks/ks1.cfg quiet

Similar way can we provide path to answer file in isolinux.cfg ?

diskless image

Hi,
would it be possible to build a diskless (read only) image?

Image not booting in kvm

I tried to build a KVM qemu image, but it's not booting. Most probably, I did something wrong, but I'm unable to find it.

My environment:

[root@lab2 ~]# virsh --version
4.5.0
[root@lab2 ~]# qemu-img --version | head -1
qemu-img version 1.5.3, Copyright (c) 2004-2008 Fabrice Bellard
[root@lab2 ~]# cat /etc/redhat-release 
Red Hat Enterprise Linux Server release 7.9 (Maipo)

I use a GitHub workflow to build it, more or less the same as yours:
https://github.com/tuxpeople/libvirt-alpine-playground/blob/master/.github/workflows/release.yml

I already tried it with your example files, but I'm also unable to boot it with them. But for the record, this are mine:

• https://github.com/tuxpeople/libvirt-alpine-playground/blob/master/packages
• https://github.com/tuxpeople/libvirt-alpine-playground/blob/master/repositories
• https://github.com/tuxpeople/libvirt-alpine-playground/blob/master/configure.sh

I use this script to deploy it: https://github.com/tuxpeople/libvirt-alpine-playground/blob/master/labdeploy.sh

Basically, what I do is this:

• download the image
• make a copy for the vm
• create the vm

wget ${IMG} -O /data/virt/images/alpine-playground.qcow2
qemu-img create -q -f qcow2 -F qcow2 -b /data/virt/images/alpine-playground.qcow2 $DISK
qemu-img resize $DISK $DISK_SIZE
virsh \
    pool-create-as \
    --name=${VMNAME} \
    --type=dir \
    --target=${VMDIR}/${VMNAME} \

virt-install \
    --import \
    --name=${VMNAME} \
    --memory=2048 \
    --vcpus=1 \
    --cpu=host \
    --disk=${VMNAME}.qcow2,bus=virtio \
    --network=bridge=bridge99,model=virtio \
    --os-variant=auto \
    --noautoconsole \
    --graphics=spice,port=-1,listen=localhost

When I connect to the console, nothing displays. Also no errors anywhere... Do you have an idea?

Image with xfs does not work

I have found a bug. I tried to create an image with xfs file system. But the system does not boot when I chose xfs.
I also have a possible patch ready.
But it creates a partition. It is unfortunately needed as it seems.
That would maybe also help with #1.

Support root-less mode via libguestfs

This script currently requires root privileges due to its usage of qemu-nbd. This could be replaced with guestmount/guestunmount to provide root-less operation.
Unfortunately it seems that libguestfs is not yet packaged in Alpine, but it is in a lot of other distros.

Help / Suggestions how to get this working with OVH?

Hello,

I'm building an image (on an Alpine 3.18 host) for deployment on OVH bare metal, using the following:

alpine-make-vm-image --image-format qcow2 \
--image-size 2G \
--boot-mode UEFI \
--packages "chrony doas doas-sudo-shim less logrotate openssh ssmtp" \
--script-chroot  \
alpine.qcow2 -- ./configure.sh

The built image is available here: https://jordanschatz.com/alpine.qcow2

When loading it in OVH via their BYOI (bring-your-own-image)

After installing the host does not respond to a ping. Using IPMI the host hangs (?) after booting to EFI

Any suggestions how to debug or what to try?

Thank you!

alpine-base not listed as installed?

Running the commands

echo apk info > foo.sh
chmod +x foo.sh
alpine-make-vm-image -f qcow2 -- foo.img foo.sh

inside a privileged alpine docker container successfully creates image foo.img, and
log shows apk info listed 43 packages...
but not alpine-base, which is odd because
alpine-make-vm-image clearly seems to install it, and its
files (e.g. /etc/issue) are present.

apk add fails with certificate verify failed error on Fedora

Using the script on a Fedora F31 host.
Invocation as follows:

$ sudo ./alpine-make-vm-image -p dropbear -c -f qcow2 ./alpine-latest-stable-virt.qcow2 ./setup.sh

> apk not found, downloading static apk-tools
...
> Attaching image ./alpine-lates-stable-virt.qcow2 as a NBD device
> Formatting image to ext4
> Mounting image at /tmp/alpine-make-vm-image.ea2BE2
> Installing base system
fetch https://nl.alpinelinux.org/alpine/v3.11/x86_64/APKINDEX.tar.gz
139868176543548:error:14007086:SSL routines:CONNECT_CR_CERT:certificate verify failed:ssl_clnt.c:1037:
ERROR: https://nl.alpinelinux.org/alpine/v3.11: Permission denied
WARNING: Ignoring APKINDEX.17ae85cd.tar.gz: No such file or directory
fetch https://nl.alpinelinux.org/alpine/v3.10/main/x86_64/APKINDEX.tar.gz
139868176543548:error:14007086:SSL routines:CONNECT_CR_CERT:certificate verify failed:ssl_clnt.c:1037:
ERROR: https://nl.alpinelinux.org/alpine/v3.10/main: Permission denied
WARNING: Ignoring APKINDEX.4bf59d7e.tar.gz: No such file or directory
fetch https://nl.alpinelinux.org/alpine/v3.10/community/x86_64/APKINDEX.tar.gz
139868176543548:error:14007086:SSL routines:CONNECT_CR_CERT:certificate verify failed:ssl_clnt.c:1037:
ERROR: https://nl.alpinelinux.org/alpine/v3.10/community: Permission denied
WARNING: Ignoring APKINDEX.06796e8e.tar.gz: No such file or directory
ERROR: unsatisfiable constraints:
  alpine-base (missing):
    required by: world[alpine-base]
/dev/nbd15 disconnected
$

The error is on this line, which is the 1st invocation of apk:

_apk add --root . --update-cache --initdb alpine-base

For now I specified the repository URL / mirror URI as an option with http only, so my invocation looks like this to get around it:

$ sudo ./alpine-make-vm-image --mirror-uri http://nl.alpinelinux.org/alpine -p dropbear -c -f qcow2 ./alpine-latest-stable-virt.qcow2 ./setup.sh

The other workaround I have found is to copy a CA bundle into a file at /etc/ssl/cert.pem on the Fedora host.
Fedora has the CA bundles originally as follows:
/etc/ssl/ has one sym link certs (nothing else), and certs is a symbolic link to /etc/pki/tls/certs dir, which then has two cert bundles
ca-bundle.crt -> /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
ca-bundle.trust.crt -> /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt
Also, /etc/pki/tls/ has a cert.pem -> /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem.

I tried it on another non-Alpine host (Gentoo, which yet arranges the CA bundles differently) and do not have the issue, so must be related to Fedora's way of arranging the CA bundles. Maybe the issue is in the static APK tools' logic to locate the cert bundle.

Fails in Docker for Mac 2.4?

The script I'd been happily using was broken by the Docker for Mac 2.4.0.0 update
that was pushed out today. The symptom was:

mkfs.ext4: I/O error while writing out and closing file system

Downgrading to Docker 2.3.0.5 worked around the problem.

I tried to come up with a minimal reproducer to submit to the Docker guys, but so far failed. This is where I left it:

# Run with 'docker build -t nbdbug . && docker run --privileged -t nbdbug'
FROM alpine:3.12
RUN apk update && apk add qemu-img e2fsprogs
CMD \
   find /dev -maxdepth 2 -name 'nbd[0-9]*' && \
   qemu-img create -f qcow2 dummy.img 500M && \
   qemu-nbd --connect=/dev/nbd1 --cache=writeback --format=qcow2 dummy.img && \
   mkfs.ext4 -L root -O ^64bit -E nodiscard /dev/nbd1 && \
   qemu-nbd --disconnect /dev/nbd1

but that also succeeds on the new docker. /me is perplexed.

This also affected a coworker who was using docker's Edge version, so he saw it before I did.

building with --rootfs btrfs fails

logs:

> Setting up extlinux bootloader
(1/3) Installing mtools (4.0.36-r0)
(2/3) Installing blkid (2.37.2-r1)
(3/3) Installing syslinux (6.04_pre1-r9)
OK: 47 MiB in 37 packages
/boot is device /dev/nbd14
Warning: unable to obtain device geometry (defaulting to 64 heads, 32 sectors)
         (on hard disks, this is usually harmless.)
/dev/nbd14 disconnected

it fails at lines 275-276

	chroot "$mnt" update-extlinux --warn-only 2>&1 \
		| grep -Fv 'extlinux: cannot open device /dev' >&2

i am not entirely sure what the grep is for, but when omitting it the image builds fine (and boots fine too)

is it possible to build image for other architecture?

VM does not boot or get IP from dhcp

By default eth0 is DOWN for some reason, I've to enable it manually and then call udhcpc to get IP address. Any pointers @jirutka thanks.

Please provide example for creating an amd64 alpine image with command line only.

Hi,

Please provide example for creating an amd64 alpine image with command line only.

Failed to load Boot0001 "UEFI Misc Device": Not Found

Hi! I am trying to build an aarch64 image using the new instructions provided (I've been building x86 images with this script for awhile! Thanks!) and unfortunately I can't get anything to boot. Here is how I am calling alpine-make-vm-image:

sudo ./alpine-make-vm-image \
--arch=aarch64 \
--image-format=qcow2 \
--rootfs=ext4 \
--packages="$(cat packages) linux-virt@edge" \
--repositories-file=repositories \
--script-chroot \
alpine-aarch64.qcow2 -- \
./script.sh

I am running this build on a Fedora 38 x86 system. I get the following error while trying to boot the output image:

failed to load Boot0001 "UEFI Misc Device" from PCIRoot ... : Not Found

I'm not entirely sure what is going on, and in the boot menu there doesn't seem to be any other devices available. An x86 image (which boots via BIOS, not UEFI) works just fine. I'm using commit 2478069 of the script to run these builds.

Thanks for any help you can provide!

Option -v prints usage text

This is not a big issue. I just wanted to note that the option -v prints the usage while the long option --version works as expected.
Thank you and please keep the good work!

Auto-retrieve `/etc/apk/keys` and `/etc/apk/packages`

On a non-alpine machine these do not exist and the requirements as mentioned in the README and project docs are misleading in that they only do not mention this requirement.

Keys could be retrieved from https://alpinelinux.org/keys/, though not all of them are in /etc/apk/keys.

For repositories it would be good to have a fallback (http://dl-cdn.alpinelinux.org/alpine/latest-stable/main ?) or use the setup-apkrepos script somehow.

The outout of `fdisk -l` is confused on the vm

I use the following command to create a image.

sudo -E ./alpine-make-vm-image -f qcow2 -s 512M --mirror-uri http://mirrors.ustc.edu.cn/alpine -k lts -p "e2fsprogs-extra parted" -t -- alpinelinux.qcow2

I use virt-install create a vm with the following command

virt-install --name alpinelinux --os-variant alpinelinux3.8 --noautoconsole --import --memory=128 --vcpus=1 --cpu host --disk path=/work/libvirt/runtime/alpinelinux.qcow2,bus=virtio --network bridge=virbr0,model=virtio

Then attach the console with virsh console alpinelinux

Connected to domain alpinelinux
Escape character is ^]

Welcome to Alpine Linux 3.15
Kernel 5.15.16-0-lts on an x86_64 (/dev/ttyS0)

localhost login: root
Welcome to Alpine!

The Alpine Wiki contains a large amount of how-to guides and general
information about administrating Alpine systems.
See <http://wiki.alpinelinux.org/>.

You can setup the system with the command: setup-alpine

You may change this message by editing /etc/motd.

localhost:~# fdisk -l
Disk /dev/vda: 512 MB, 536870912 bytes, 1048576 sectors
1040 cylinders, 16 heads, 63 sectors/track
Units: sectors of 1 * 512 = 512 bytes

Device  Boot StartCHS    EndCHS        StartLBA     EndLBA    Sectors  Size Id Type
/dev/vda1 09 187,180,14  784,0,13    3224498923 3657370039  432871117  206G  7 HPFS/NTFS
/dev/vda2 f4 906,235,61  262,116,59  3272020941  930513678 1953460034  931G 16 Hidden FAT16
/dev/vda3 20 370,101,50  10,114,13            0          0          0     0 6f Unknown
/dev/vda4    0,0,0       0,0,0         50200576  974536369  924335794  440G  0 Empty

Partition table entries are not in disk order
localhost:~# df -h
Filesystem                Size      Used Available Use% Mounted on
devtmpfs                 10.0M         0     10.0M   0% /dev
shm                      47.5M         0     47.5M   0% /dev/shm
/dev/vda                487.9M    120.9M    331.2M  27% /
tmpfs                    19.0M     48.0K     19.0M   0% /run
cgroup_root              10.0M         0     10.0M   0% /sys/fs/cgroup

localhost:~# parted -l /dev/vda
Model: Virtio Block Device (virtblk)
Disk /dev/vda: 537MB
Sector size (logical/physical): 512B/512B
Partition Table: loop
Disk Flags:

Number  Start  End    Size   File system  Flags
 1      0.00B  537MB  537MB  ext4

It's obvious that fdisk -l /dev/vda return the wrong information. I searched with google but do not found an answer. Did you know why?

lts kernel flavor results in broken /sysroot mount path

When building an image with the lts kernel-flavor, the resulting image isn't able to find the root fs to mount.

I'm using sudo ./alpine-make-vm-image --image-format qcow2 --kernel-flavor lts alpine-test.qcow2 to build the image and sudo kvm -smp 8 -drive file=alpine-test.qcow2 to test in qemu. Replacing the kernel-flavor with the default virt kernel works just fine.

apk update not working with other user then root

I am behind a corporate proxy http://proxy_ip:port , getting below error while using apk update command as user

ERROR: https://dl-cdn.alpinelinux.org/alpine/v3.17/main/: temporary error (try again later) fetch https://dl-cdn.alpinelinux.org/alpine/v3.17/community/x86_64/APKINDEX.tar.gz ERROR: https://dl-cdn.alpinelinux.org/alpine/v3.17/community/: temporary error (try again later) fetch https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz ERROR: https://dl-cdn.alpinelinux.org/alpine/edge/testing/: temporary error (try again later)

but works fine with root login

is it possible to build image for s390x architecture?

Can't run in docker?

Running in an alpine linux docker container on mac fails with

> Attaching image foo.img as a NBD device
modprobe: can't change directory to '/lib/modules': No such file or directory
ERROR: No available nbd device found!

nbd seems like overkill when creating raw images; using a loopback mount for the raw image case
might let the script run in docker.

How do I configure this to install a MBR and Grub?

Hey as the title says, some cloud providers require that grub be setup with the disk image.

Can't run in docker inside github workflow CI

See #15

Works fine in github... unless you try to use it inside docker, where it fails with

modprobe: can't change directory to '/lib/modules': No such file or directory
ERROR: No available nbd device found!

Looking around for ideas:

• alpine-make-vm-image could fall back to guestmount from http://libguestfs.org
• users could run alpine-make-vm-image using qemu, possibly via a nice wrapper like https://github.com/multiarch/qemu-user-static, https://github.com/dbhi/qus, or https://github.com/gotoz/runq

I forked this project to https://github.com/dankegel/alpine-make-vm-image/tree/test-on-github, added a .github/workflows/test.yml to test running on github, and then gave libguestfs the old college try.
Unfortunately, I couldn't get libguestfs to work inside docker, even locally.
But the branch is there in case anyone wants a look.

For now, the best option is still don't run inside docker on github :-)

The getopt of alpine-make-vm-image does not handle -m

Please refer to

sudo -E ./alpine-make-vm-image -f qcow2 -s 512M -m http://mirrors.ustc.edu.cn/alpine -k lts -p linux-firmware-none -- alpine.qcow2
alpine-make-vm-image: invalid option -- 'm'
Usage: alpine-make-vm-image [options] [--] <image> [<script> [<script-opts...>]]

This script creates a bootable Alpine Linux disk image for virtual machines.
If running on Alpine system (detected by file /etc/alpine-release), then it
also installs needed packages on the host system. On other systems you must
install them yourself: qemu-img, qemu-nbd, and mkfs utility for the chosen
ROOTFS. If $APK is not available on the host system, then static apk-tools
specified by $APK_TOOLS_URI is downloaded and used.

I check the code and find getopt -n $PROGNAME -o b:cCf:hi:k:p:r:s:tv. When I change it to getopt -n $PROGNAME -o b:cCf:hi:k:m:p:r:s:tv. It's OK.

I like this tool, it's simple and my packer script is powerful but it's complex!