Build configuration

The following provides a reference of the file build.xml residing in a build configuration directory.

Build configuration structure

The XML-attributes used in the build configuration file build.xml (find example configurations below):

  • build-vm - the VM used to bootstrap the target-vm
    • arch - specifies the build-vm architecture
    • name - the build-vm name
    • version - the build-vm version
    • hash-algorithm - the hash-algorithm used for the hash creation over the raw build-vm image
    • hash - the hash of the raw build-vm image
  • source-vm - the VM the build should inherit from
    • arch - specifies the source-vm architecture
    • name - the source-vm name
    • version - the source-vm version
    • hash-algorithm - the hash-algorithm used for the hash creation over the raw source-vm image
    • hash - the hash of the raw source-vm image
  • target-vm - the VM to be build
    • arch - specifies the target-vm architecture
    • name - the target-vm name
    • version - the target-vm version
    • hash-algorithm - the hash-algorithm used for the hash creation over the raw target-vm image
    • hash - the hash of the raw target-vm image
  • jobs - The actions to be run by the builder.
    • create-disk - Create a new disk with a specified size.
      • size - specifies the size of the new disk.
    • resize-disk - Resize an existing disk with a specified size.
      • size - specifies the size of the existing disk.
    • label - Label a disk.
      • type - specifies the type of label (msdos, gpt).
    • partition - Create partitions
      • type - specifies the type of partition (primary, extended, logical).
      • start - the partition offset
      • size - the partition size
    • format - Format partitions.
      • partition - specifies which partition to format
      • type - the partition format (ext2, ext3, ext4, fat32, ntfs, ufs, ufs2, xfs, udf, btrfs, minix, exfat)
      • label - the partition label
      • uuid - the partition uuid
    • fetch - Download files for later copying / extraction to the VM disk.
      • url - specifies the url to the file to download
      • path - the local path of the downloaded file
      • retry - amount of retries for the download
      • hash - hash of the file
      • hash-algorithm - hash algorithm used by the hasher (sha384, sha512)
    • tar-in - Extract an archive to a partitions path.
      • partition - specifies which partition to use for extraction
      • source - the source archive file path on the host
      • target - the target path on the VM disks partition
      • file - the subset to extract
    • tar-out - Compress a path in the VM disk to an archive.
      • partition - specifies which partition to use for compression
      • source - the source path on the VM disks partition
      • target - the target archive file path on the host
    • copy-in - Copy a file or directory to the VM disk.
      • partition - specifies which partition to use for copying
      • source - the source file or directory path on the host
      • target - the target file or directory path on the VM disks partition
    • copy-out - Copy a file or directory from the VM disk.
      • partition - specifies which partition to use for copying
      • source - the source file or directory path on the VM disks partition
      • target - the target file or directory path on the host
    • dd - Copy a files content to a specific offset on the disk, to e.g. write the MBR.
      • file - the file path on the host
      • bs - the block size
      • count - the number of input blocks to write
      • seek - the offset to write to (value is multiplied by bs)
    • run - Run an arbitrary command as the target-vm, to e.g. creates users, install packages. In order to use this job, the target-vm needs to be bootable and needs to be able to run the firstrun script, see Creating a configuration for details.
      • virtio - specifies whether to use legacy or virtio hardware
      • network - whether to enable network access
      • ram - the amount of RAM to assign
      • command - the command to run as the target
    • hash - Compute a hash over the raw target-vm disk (disk0.img).
      • hash-algorithm - the hash-algorithm used for the hash creation over the raw target-vm image
      • hash - the hash of the raw target-vm image
    • diff - Export the disk in raw format, hash, then diff versions of the files on the VM disk from two consequent runs.
      • hash-algorithm - the hash-algorithm used for the hash creation over the raw target-vm image
      • hash - the hash of the raw target-vm image
    • remove - Remove a file or directory from the VM disk.
      • partition - specifies which partition to use for removing
      • target - the target file or directory path on the VM disks partition
    • export - Recreates the raw disk in order to create a reproducable image checked by hash. See the reference for supported formats.
      • format - the export format (raw performs a reformatting and sequential, ordered copying of files to a new disk to ensure a reproducable image. This is supported for the file system formats ext2, ext3, ext4, fat32, ufs, ufs2. tar.gz performs the same procedure, but additionally compresses the raw image. root.tar.gz needs the additional parameter partition and only exports the on disk files as a tar.gz archive for usage in containers for e.g. Docker, Podman and others. ova performs the same procedure as raw, but additionally converts the image to the VMDK format and creates an Open Virtualization Appliance from it, so it can be imported in Oracle VirtualBox, VMware products, Red Hat Enterprise Virtualization, Proxmox and others.)
      • hash-algorithm - the hash-algorithm used for the hash creation over the raw target-vm image
      • hash - the hash of the raw target-vm image
      • partition - used for exporting a partition as an archive in format tar.gz
      • virtio - used for exporting an Open Virtualization Appliance to specify the disk and network controller defined
      • ram - used for exporting an Open Virtualization Appliance to specify the amount of memory defined

Example build configuration

This is a minimal example of a build configuration:

<config>
  <build-vm arch="x86_64" name="linux-busybox" version="2024-05-23"/>
  <target-vm arch="x86_64" name="freebsd-13.0" version="2024-04-13"/>
  <jobs>
      <create-disk size="4G"/>
      <label type="msdos"/>
      <partition type="primary" start="1MB" size="2500MB"/>
      <format partition="1" type="ufs2" label="" uuid=""/>

      <dd file="boot.img" bs="446" count="1"/>
      <dd file="core.img" bs="512" seek="1"/>

      <fetch url="https://download.freebsd.org/ftp/releases/amd64/13.3-RELEASE/kernel.txz" path="kernel.txz" retry="3" hash="d08c54610a8ed40de103accd6171fc8abc59e0594d4e8bb8ecf8f8cf2fc8feb55422a1ee58996b6e42364140fa8bc8505d42758579da064018e98330209fc35c" hash-algorithm="sha512"/>
      <fetch url="https://download.freebsd.org/ftp/releases/amd64/13.3-RELEASE/base.txz" path="base.txz" retry="3" hash="faae230c12d8028c050de551656bb86435b5414aa605c20aaff3ac149816a3d711bbdbe867823f9ae6cb02bb56d9092a92f5913c1d07aa3ba86ef6484ce0e417" hash-algorithm="sha512"/>

      <tar-in partition="1" source="kernel.txz" target="/"/>
      <tar-in partition="1" source="base.txz" target="/"/>

      <copy-in partition="1" source="interfaces" target="/etc/network/interfaces"/>
      <copy-in partition="1" source="resolv.conf" target="/etc/resolv.conf"/>
      <copy-in partition="1" source="grub.cfg" target="/boot/grub/grub.cfg"/>
      <copy-in partition="1" source="firstrun" target="/usr/local/etc/rc.d/firstrun.sh"/>
      <copy-in partition="1" source="fstab" target="/etc/fstab"/>

      <run virtio="yes" network="yes" ram="1G" command="uname -a"/>
  </jobs>
</config>

Below is an example of:

  • all available jobs used
  • usage of hashes for the build-vm, target-vm to check for reproducibilty
  • assisting jobs to create reproducable images, such as hash, diff and export, remove
<config>
  <build-vm arch="x86_64" name="linux-busybox" version="2024-08-01" hash-algorithm="sha512" hash="a8b64975153cb2fb808acf32c84b225cd5865453955515c8af1b40ede60bd3cbe8d150c1459c767ffddeaf8e6b119e9bbdd81ff35942ea6e118efb5501bd6eef"/>
  <target-vm arch="x86_64" name="freebsd-13.0" version="2024-04-13" hash-algorithm="sha512" hash="3a867accb87275f3760cc5051b4589a1b92a64cb0b6197bf3c52b410efe636dfb36f3d6c01e878e63eaf3057c00d8d938c7c56ef1927495fbf92b67cb57d7a8e"/>
  <jobs>
      <create-disk size="4G"/>
      <label type="msdos"/>
      <partition type="primary" start="1MB" size="2500MB"/>
      <format partition="1" type="ufs2" label="" uuid=""/>

      <copy-in partition="1" source="interfaces" target="/etc/network/interfaces"/>
      <copy-out partition="1" source="/etc/network/interfaces" target="interfaces2"/>
      <copy-out partition="1" source="/etc/network" target="network2"/>
      <tar-out partition="1" source="/" target="root.tar.gz"/>

      <dd file="boot.img" bs="446" count="1"/>
      <dd file="core.img" bs="512" seek="1"/>

      <fetch url="https://download.freebsd.org/ftp/releases/amd64/13.3-RELEASE/kernel.txz" path="kernel.txz" retry="3" hash="d08c54610a8ed40de103accd6171fc8abc59e0594d4e8bb8ecf8f8cf2fc8feb55422a1ee58996b6e42364140fa8bc8505d42758579da064018e98330209fc35c" hash-algorithm="sha512"/>
      <fetch url="https://download.freebsd.org/ftp/releases/amd64/13.3-RELEASE/base.txz" path="base.txz" retry="3" hash="faae230c12d8028c050de551656bb86435b5414aa605c20aaff3ac149816a3d711bbdbe867823f9ae6cb02bb56d9092a92f5913c1d07aa3ba86ef6484ce0e417" hash-algorithm="sha512"/>
      <fetch url="https://download.freebsd.org/ftp/releases/amd64/13.3-RELEASE/lib32.txz" path="lib32.txz" retry="3" hash="07be4c7d395df2551cc696061b31fb557653123dac0a687455592911a2f217d148f98db739111d5d4668e1e72c73998b7e0dc36093b55e70b9207bab53217a8a" hash-algorithm="sha512"/>
      <fetch url="https://download.freebsd.org/ftp/releases/amd64/13.3-RELEASE/ports.txz" path="ports.txz" retry="3" hash="bcaf976dfcbf47a2d1f49a04eafea0c58c96b542d3041155666462ee3040a22e16f2cc62998c35ed028d312e62aef5667d2c4cf9d3a4a5b02771319ca4f2a7ee" hash-algorithm="sha512"/>

      <tar-in partition="1" source="kernel.txz" target="/"/>
      <tar-in partition="1" source="base.txz" target="/"/>
      <!--<tar-in partition="1" source="lib32.txz" target="/"/>-->
      <!--<tar-in partition="1" source="ports.txz" target="/"/>-->

      <copy-in partition="1" source="interfaces" target="/etc/network/interfaces"/>
      <copy-in partition="1" source="resolv.conf" target="/etc/resolv.conf"/>
      <copy-in partition="1" source="grub.cfg" target="/boot/grub/grub.cfg"/>
      <copy-in partition="1" source="firstrun" target="/usr/local/etc/rc.d/firstrun.sh"/>
      <copy-in partition="1" source="fstab" target="/etc/fstab"/>

      <run virtio="yes" network="yes" ram="1G" file="kernel.txz" command="uname -a"/>
      <remove partition="1" target="/var/log"/>
      <remove partition="1" target="/var/run/dmesg.boot"/>
      <remove partition="1" target="/boot/entropy"/>
      <remove partition="1" target="/entropy"/>
      <remove partition="1" target="/etc/hostid"/>
      <remove partition="1" target="/etc/machine-id"/>
      <diff hash-algorithm="sha512" hash="3a867accb87275f3760cc5051b4589a1b92a64cb0b6197bf3c52b410efe636dfb36f3d6c01e878e63eaf3057c00d8d938c7c56ef1927495fbf92b67cb57d7a8e"/>

      <export format="ova" virtio="true" ram="512MB" hash-algorithm="sha512" hash="657573e71303da058f5476661b5fad874df4e7b9f5224e2f323f0f0fb7fdd255902d3d5f3cafeb5e0cac2cb8682a80d1ff4a11e2cb85a6d27071d707a1cb2572"/>
      <export format="root.tar.gz" partition="1" hash-algorithm="sha512" hash="46c8b345895bdd38bd1804086ec520c29e0b95f36555ccb5037ae1a8cca0edb1448e8902f02620073dba9329316bede902ac43d87b075bea691594be94a13334"/>
      <export format="tar.gz" hash-algorithm="sha512" hash="12d32b7c5da69cf360027bbbcdfce9f05099a372ea4f1d2b600453c8afcfdd581e140197c06c8f9de34e853ca2687f49485d129967b7bb9f98fb8592fd5c8245"/>
  </jobs>
</config>

Below is an example of:

  • usage of a source-vm, a previously build image, to inherit from
  • usage of hashes for the build-vm, source-vm and target-vm to check for reproducibilty
  • a resize-disk job to bring the previously created image to a new size
<config>
    <build-vm arch="x86_64" name="linux-busybox" version="2024-08-01" hash-algorithm="sha512" hash="a8b64975153cb2fb808acf32c84b225cd5865453955515c8af1b40ede60bd3cbe8d150c1459c767ffddeaf8e6b119e9bbdd81ff35942ea6e118efb5501bd6eef"/>
    <source-vm arch="x86_64" name="linux" version="2024-07-23" hash-algorithm="sha512" hash="afdbcaac1d49b77972e91e2a18e862e0c24380944f4ccadd5687fcb2a17bb3256a827c9aca70bea7aa98e9d0c81f19097a20435daa13f00ee5694cb0498b390e"/>
    <target-vm arch="x86_64" name="nixos" version="2024-07-23" hash-algorithm="sha512" hash="7d988bc18943fb985248a3e69bfd13a6d9ae55911bc2867ccf4e41d5c3044804e2cd2c18e171c024a432aede658d4d07ec2b769c6b36a5c234efd530da1a9e69"/>
    <jobs>
        <resize-disk size="6G"/>
        <run virtio="yes" network="yes" ram="1024M" command="uname -a"/>
        <fetch url="https://releases.nixos.org/nix/nix-2.23.3/install" path="nix-install" retry="3" hash="20f7a01bef61f2c99644b0e677be0532b99a9406955c469b6a8f9f5f8c17c8b963e497afaf13b3ae70bebf777ab7b99b72424e8b4a2984462cbc1cc337bbce16" hash-algorithm="sha512"/>
        <copy-in partition="1" source="nix-install" target="/sbin/nix-install"/>
        <copy-in partition="1" source="setup.sh" target="/opt/setup.sh"/>
        <copy-in partition="1" source="configuration.nix" target="/etc/nixos/configuration.nix"/>
        <copy-in partition="1" source="hardware-configuration.nix" target="/etc/nixos/hardware-configuration.nix"/>
        <run virtio="yes" network="yes" ram="1536M" command="/opt/setup.sh"/>
        <copy-in partition="1" source="firstrun" target="/sbin/firstrun"/>
        <run virtio="yes" network="yes" ram="1024M" command="uname -a"/>
        <copy-in partition="1" source="configuration-update.nix" target="/etc/nixos/configuration.nix"/>
        <run virtio="yes" network="yes" ram="1024M" command="nixos-rebuild switch"/>
    </jobs>
</config>