Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jerome-maurin/vmdb2-wrapper

Simple wrapper for vmdb2, to build armhf & arm64 board images for SD-card using u-boot Debian packages, flash-kernel and Debian kernels
https://github.com/jerome-maurin/vmdb2-wrapper

ansible arm64-images armhf-images board bootable-media cubieboard-images debian debian-kernels debian-linux debian-packages debootstrap linux odroid-images pine64-images qemu-debootstrap sd-card-image u-boot uboot-debian-packages vmdb2 yaml-files

Last synced: 3 months ago
JSON representation

Simple wrapper for vmdb2, to build armhf & arm64 board images for SD-card using u-boot Debian packages, flash-kernel and Debian kernels

Awesome Lists containing this project

README 

        
# VMDB2-Wrapper



[![actions build ](https://github.com/Jerome-Maurin/vmdb2-wrapper/workflows/Build%20images%20matrix/badge.svg)](https://github.com/Jerome-Maurin/vmdb2-wrapper/actions)



VMDB2-Wrapper is a simple wrapper for [`vmdb2`](https://vmdb2.liw.fi/), 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](https://gitlab.com/larswirzenius/vmdb2/) or [his own Gitano server](http://git.liw.fi/vmdb2/).



The Raspberry Pi different models are already [supported by Debian](https://raspi.debian.net).


FYI these images are also [build using `vmdb2`](https://salsa.debian.org/raspi-team/image-specs/).



# Table of contents



- [Supported Platforms](#supported-platforms)

- [TL;DR Getting started](#tldr-getting-started)

- [How to build an image](#how-to-build-an-image)

  * [Setting up the environment](#setting-up-the-environment)

  * [Choosing the right target](#choosing-the-right-target)

  * [Building the image](#building-the-image)

- [Writing the image to an SD-card](#writing-the-image-to-an-sd-card)

- [Customizing the image by using an Ansible-playbook](#customizing-the-image-by-using-an-ansible-playbook)

- [Needed packages](#needed-packages)

- [FAQ](#faq)

  * [Why must the build be run as root?](#why-must-the-build-be-run-as-root-)

  * [How to add the support for a new board?](#how-to-add-the-support-for-a-new-board-)

- [Potential issues](#potential-issues)

  * [Cleanup old cache](#cleanup-old-cache)



# Supported Platforms



FIXME



# TL;DR Getting started



You can either download an already built image from [the project's Github Releases](https://github.com/Jerome-Maurin/vmdb2-wrapper/releases) or [the project's Github Actions (nigthly builds)](https://github.com/Jerome-Maurin/vmdb2-wrapper/actions) (needs to be logged-in) and then skip to the [**Writing the image to an SD-card**](#writing-the-image-to-an-sd-card) section.



### Or



You can build the image yourself using a Debian (or an Ubuntu, you'll need to adapt the Debian procedure).



# How to build an image



## Setting up the environment (Bookworm)



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**](#needed-packages) section.



### Building on Buster



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](https://wiki.debian.org/AptConfiguration#apt_preferences_.28APT_pinning.29)) or retrieve and install [the Bullseye package](https://packages.debian.org/bullseye/all/vmdb2/download) 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



### Building on Bullseye



vmdb2 version 0.22.



Installing zerofree is not needed in this version.



FIXME



## Choosing the right target



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 of `vmdb2` are retro-compatible with older yaml files versions (0.14.1 yaml files will work with version 0.14.1+).



## Building the image



For the time being `vmdb2` needs to be run as root, see [**Why must the build be run as root?**](#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



### Or



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`



# Writing the image to an SD-card



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



# Default login



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.



# Customizing the image by using an Ansible-playbook



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`.



# Needed packages



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)](http://git.liw.fi/vmdb2/commit/?id=470b0a05ad7717139897f08e24f48d6fedc2a8d6a).



Unfortunately, the [dependency list in the Bookworm package](https://packages.debian.org/bookworm/vmdb2) is missing zerofree, which means we need to install it manualy.



This is fixed in [Trixie](https://packages.debian.org/trixie/vmdb2).



******************************



`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.



# FAQ



## Why must the build be run as root?



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.



## How to add the support for a new board?



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



# Potential issues



## Cleanup old cache



If you face any issue when running the built image, try removing the corresponding cache file `RELEASE_ARCH_rootfs.tbz` and rebuilding the image.