VMDB2-Wrapper is a simple wrapper for vmdb2, to build armhf & arm64 board images for SD-card using u-boot Debian packages, flash-kernel and Debian kernels.
Source code for vmdb2 can be found on Lars Wirzenius' Gitlab or his own Gitano server.
The Raspberry Pi different models are already supported by Debian.
FYI these images are also build using vmdb2.
- Supported Platforms
- TL;DR Getting started
- How to build an image
- Writing the image to an SD-card
- Customizing the image by using an Ansible-playbook
- Needed packages
- FAQ
- Potential issues
FIXME
You can either download an already built image from the project's Github Releases or the project's Github Actions (nigthly builds) (needs to be logged-in) and then skip to the Writing the image to an SD-card section.
You can build the image yourself using a Debian (or an Ubuntu, you'll need to adapt the Debian procedure).
On a freshly installed minimalist Debian Bookworm (with sudo installed), use this command to install needed packages:
sudo apt install vmdb2 zerofree curl ansible python3-distutils qemu-user-static binfmt-support
The purpose behind each of those packages is explained in the Needed packages section.
vmdb2 version 0.13.2.
Installing zerofree is not needed in this version.
The vmdb2 version in Debian Buster lacks a critical feature which forces the installation of Bullseye's version.
Either add the Bullseye repository to your sources.list (be careful to limit the package to vmdb2) or retrieve and install the Bullseye package manually.
For example (manual install):
wget http://ftp.de.debian.org/debian/pool/main/v/vmdb2/vmdb2_0.22-1_all.deb
sudo apt install ./vmdb2_0.22-1_all.deb
vmdb2 version 0.22.
Installing zerofree is not needed in this version.
FIXME
Each Yaml file corresponds to a single board using the naming convention BOARD_RELEASE_ARCH_vmdb2-MINVERSION.yaml where:
- BOARD is the board's name.
- RELEASE is the expected Debian release.
- ARCH is the expected architecture (armhf or arm64 for example).
- MINVERSION is vmdb2's minimum required version for the Yaml file to work.
FYI versions ofvmdb2are retro-compatible with older yaml files versions (0.14.1 yaml files will work with version 0.14.1+).
For the time being vmdb2 needs to be run as root, see Why must the build be run as root? for more details.
Use head on the file corresponding to your board and run the command present in the comment on the first line.
vmdb2 command generic example:
sudo vmdb2 BOARD_RELEASE_ARCH_vmdb2-MINVERSION.yaml --output BOARD_RELEASE_ARCH.img --rootfs-tarball RELEASE_ARCH_rootfs.tgz --log=stderr
You can run the following oneliner if you prefer:
eval $(head -n1 BOARD_RELEASE_ARCH_vmdb2-MINVERSION.yaml | sed 's/^.*: \(.*\)$/\1/g')
The resulting image will be called BOARD_RELEASE_ARCH.img
To write the .img file to an sdcard, use dd.
For example:
sudo dd bs=64k status=progress oflag=dsync if=cubietruck_buster_armhf.img of=/dev/mmcblk1
Make sure /dev/mmcblkN is the correct SD-card (by using lsblk for example).
In case the image comes from Github Releases or Github Actions you could use something like that:
zcat cubietruck_buster_armhf.img.bz2.zip | bunzip2 -c -d | sudo dd bs=64k status=progress oflag=dsync of=/dev/mmcblk1
As vmdb2 produces a standard Debian distribution, there is a default root
account, that is passwordless. If you boot a "factory" image, just enter the
login root; no password will be prompted, and you will have full access to
the system.
For Ansible use vmdb2-ansible.yaml.exemple as a starting point, create a file named vmdb2-ansible.yaml to write an Ansible-playbook that will be used by vmdb2.
Why do I need those packages on my system to run a image build?
zerofree is needed by vmdb2 since version 0.25 (see here).
Unfortunately, the dependency list in the Bookworm package is missing zerofree, which means we need to install it manualy.
This is fixed in Trixie.
curl is needed to fetch some binaries from the internet.
ansible is needed for the build to support customizing the image with an ansible playbook.
In some cases the needed package python3-distutils might not be installed, which can trigger an error in the ansible part.
Make sure it is installed.
You can always comment or remove the call to ansible roles in the yaml files if you don't want to install it.
Extra packages needed for cross-compile build (use of qemu-debootstrap in yaml, default):
qemu-user-static and binfmt-support
You can always replace qemu-debootstrap by debootstrap to build natively without needing qemu-user-static & binfmt-support, but in case you don't want to change the yaml files and you don't mind having qemu-user-static & binfmt-support on your system, qemu-debootstrap will also work for native builds with almost no overhead.
For the time being it is easier to be root for the abilities to create /dev/loops and mount/unmount them.
An alternative could be available later.
The best starting point is the cubieboard2_buster_armhf_vmdb2-0.14.1.yaml file which is the simplest.
FIXME
Is the card supported by flash kernel?
If not, ..., comment the rm of /etc/flash-kernel/machine, if not kernel update wont work
Same if flash-kernel cannot retrieve the card's name by looking in /proc/device-tree/model
For example in case something else than U-Boot is used as bootloader
FIXME
If you face any issue when running the built image, try removing the corresponding cache file RELEASE_ARCH_rootfs.tbz and rebuilding the image.