parabola-vmbootstrap/README

parabola-vmbootstrap
====================

This is a collection of scripts for creating and booting parabola virtual
machine images for use with qemu.

virtual machine image creation
------------------------------

To create a new virtual machine image, run

  $> ./pvmbootstrap.sh [path to image] [arch]

where arch is one of the supported parabola arches, which are currently:

  official:   [ i686, x86_64, armv7h ]
  unofficial: [ ppc64le, riscv64 ]

the script will attempt to bootstrap a virtual machine of the selected
archituecture in the output file specified. If the output file already exists,
the script will emit a warning and ask for confirmation to proceed.

the creation can be influenced by providing one or more of the following
arguments to pvmbootstrap.sh:

  -s size   -- set the size of the created VM image (default: 64G)
  -M mirror -- set the mirror to fetch packages from
               (default: https://repo.parabola.nu/$repo/os/$arch)
  -H hook   -- add a confiuration hook to be executed. this can be the path to
               a shell script or one of the existing hooks described below

The creation hooks currently supported are:

ethernet-dhcp:

  this hook will setup ethernet in the VM by enabling systemd-resolved and
  openresolv properly, as well as creating and enabling a systemd-networkd
  configuration.

virtual machine boot
--------------------

To boot a created virtual machine, run:

  $> ./pvmboot.sh [path to image] [additional qemu args...]

the script will attempt to determine the architecture of the provided virtual
machine image, and set the qemu executable and sane default flags for the qemu
invocation automatically, including kvm acceleration, if available for the
target architecture.

additionally, the script will evaluate the DISPLAY environment variable to
determine whether a graphical desktop environment is available, and will start
the image in serial console mode if necessary. This behavior can be forced by
unsetting DISPLAY before executing the script:

  $> DISPLAY= ./pvmboot.sh [...]

The default flags can be overwritten or extended, for example to allocate more
memory to the machine, by specifying additional qemu parameters on the command
line following the virtual machine image name:

  $> DISPLAY= ./pvmboot [path to image] -m 2G

release tarball creation
------------------------

To convert a virtual machine image into a parabola release tarball, run:

  $> ./pvm2tarball.sh [path to image]

This will attempt to mount the rootfs and the /boot partition, and tar the
contents to an output file, filtering out all unneeded files.